F0: fondamenta della soluzione, script, documenti e harness di test

- ViaFerrea.sln con Core e Protocol (net10.0 + net8.0), Server, Tools, Tests
- Directory.Build.props con versione unica e warning come errori
- Script build/test/check-nuget/publish-image (+ build.ps1)
- Documenti: GUIDA, GDD, ARCHITECTURE, PROTOCOL (bozza), STATE, ADR 0001
- Harness di test interno con i primi test su Rng (xoshiro256**)
- Immagini di riferimento 01-05

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0191R7vXgtbAvSV4V8tj8uzL
This commit is contained in:
Claude committed 2026-10-01 21:50:41 +00:00
1 parent 63a7a460d3
commit 290a1d886c
36 files changed
+1647 -2

No files matched your search

+14
View File
@@ -427,3 +427,17 @@ FodyWeavers.xsd
*.msix
*.msm
*.msp
# --- Via Ferrea ---
# Godot
.godot/
client/ViaFerrea.Client/.godot/
client/ViaFerrea.Client/export/
# Output degli strumenti e dei test
/out/
/artifacts/
*.kpi.csv
# Volume locale del server in Docker
docker/data/
# Salvataggi locali di sviluppo
/saves/
+38
View File
@@ -0,0 +1,38 @@
# CLAUDE.md — Via Ferrea
Gestionale ferroviario dall'alto: motore headless in C# (.NET 10), server ASP.NET Core in Docker, client Godot 4 .NET.
La specifica vincolante è `docs/GUIDA.md`; lo stato dei lavori è in `docs/STATE.md`. Leggili entrambi a inizio sessione.
## Comandi
```
scripts/build.sh # check-nuget + build Release della soluzione
scripts/test.sh [filtri] # build + validate-data + tutti i test (--skip-slow, --serial)
dotnet run --project tests/ViaFerrea.Tests -- --list
dotnet run --project src/ViaFerrea.Tools -- <comando> # validate-data, genmap, profile, simulate, bench, replay
```
## Regole non negoziabili
- Zero `PackageReference` in tutta la soluzione (`scripts/check-nuget.sh`). Unica eccezione: l'SDK Godot nel client.
- Identificatori in inglese; commenti, documentazione e testi UI in italiano.
- Nessun numero magico nella simulazione: i parametri stanno in `data/*.json` (con schema in `data/schema/`).
- Simulazione deterministica: solo `Rng` (xoshiro256**) con `Fork`, niente `Random`/`Guid.NewGuid`/`DateTime.Now`/`Environment.TickCount`, niente iterazione di `Dictionary`/`HashSet` per produrre effetti, funzioni trascendenti solo da `DMath`, denaro in `Money` (centesimi).
- Core e Protocol compilano anche per net8.0 (client Godot): niente API successive a .NET 8 lì.
- Il client non contiene logica di gioco; il server è autorevole.
- Ogni decisione non coperta dalla guida → `docs/adr/NNNN-titolo.md`.
## Flusso di lavoro
- Una fase alla volta (sezione 16 della guida). Fine fase: build verde, test verdi, `docs/STATE.md` aggiornato, commit `F<n>: <cosa>`.
- Nuovi test nel harness interno (`[Test]`, `Assert`), un file per area in `tests/ViaFerrea.Tests/<Area>/`.
- I test lunghi si marcano `[Test(Slow = true)]`.
## Mappa del codice
- `src/ViaFerrea.Core` — Common, Time, Data, Map, Economy, Rail, Commands, Simulation, Persistence (vedi `docs/ARCHITECTURE.md`).
- `src/ViaFerrea.Protocol` — frame e messaggi (vedi `docs/PROTOCOL.md`).
- `src/ViaFerrea.Server` — GameLoop, sessioni WebSocket, API HTTP.
- `src/ViaFerrea.Tools` — `viaferrea-tools`.
- `client/ViaFerrea.Client` — progetto Godot.
- `reference/` — immagini di riferimento visivo vincolanti.
+20
View File
@@ -0,0 +1,20 @@
<Project>
<!-- Impostazioni comuni a tutti i progetti .NET di Via Ferrea (il client Godot ha il proprio). -->
<PropertyGroup>
<!-- Unica fonte della versione: letta anche da scripts/publish-image.sh e dal protocollo. -->
<Version>0.1.0</Version>
<Nullable>enable</Nullable>
<ImplicitUsings>enable</ImplicitUsings>
<LangVersion>latest</LangVersion>
<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
<InvariantGlobalization>true</InvariantGlobalization>
<Deterministic>true</Deterministic>
<Authors>Via Ferrea</Authors>
<Product>Via Ferrea</Product>
<Copyright>Via Ferrea</Copyright>
<SatelliteResourceLanguages>it;en</SatelliteResourceLanguages>
<GenerateDocumentationFile>false</GenerateDocumentationFile>
<!-- Nessun pacchetto NuGet: niente audit verso feed esterni. -->
<NuGetAudit>false</NuGetAudit>
</PropertyGroup>
</Project>
+55 -2
View File
@@ -1,2 +1,55 @@
# TrainGame
Game train
# Via Ferrea
Gestionale ferroviario visto dall'alto, ambientato dal 1850 in una regione immaginaria: binari con pendenze, trincee, ponti e gallerie; economia con prezzi globali e locali; pendolarismo di lavoratori e personale; manutenzione per componente di treni e industrie; concorrenti IA, borsa e scalate; un mondo che non finisce mai.
Il motore di gioco è headless e deterministico (C# su .NET 10) e gira sia dentro il client desktop (Godot 4 .NET) sia come server Linux in Docker.
## Requisiti
- .NET SDK 10.x (`dotnet --version`)
- Godot 4 .NET, versione stabile più recente, come `godot` nel PATH (solo per il client)
- Docker (solo per l'immagine del server)
## Compilare e provare
```
scripts/build.sh # controllo "zero NuGet" + build Release
scripts/test.sh # validazione dei dati + tutti i test
```
Su Windows: `./scripts/build.ps1 -Test`.
## Struttura
| Cartella | Contenuto |
|---|---|
| `src/ViaFerrea.Core` | simulazione, dati, mappa, economia, rete ferroviaria, salvataggi |
| `src/ViaFerrea.Protocol` | protocollo binario su WebSocket |
| `src/ViaFerrea.Server` | server autorevole (Kestrel) |
| `src/ViaFerrea.Tools` | `viaferrea-tools`: validate-data, genmap, profile, simulate, bench, replay |
| `tests/ViaFerrea.Tests` | harness di test interno e scenari |
| `client/ViaFerrea.Client` | client Godot |
| `data/` | parametri di gioco in JSON con schema |
| `docker/` | Dockerfile, compose, template Unraid |
| `docs/` | guida, GDD, architettura, protocollo, stato, ADR |
| `reference/` | immagini di riferimento visivo |
## Server in Docker
```
docker compose -f docker/docker-compose.yml up -d
curl http://localhost:7400/health
```
Variabili principali: `VF_TOKEN` (obbligatoria in rete), `VF_DIFFICULTY`, `VF_SEED`, `VF_MAP_SIZE`, `VF_DATA_DIR` (default `/data`).
Il server parla WebSocket in chiaro: per l'uso fuori da una rete privata mettilo dietro un reverse proxy con TLS (per esempio Caddy, Traefik o Nginx Proxy Manager su Unraid) ed esponi solo `wss://`.
## Documentazione
- `docs/GUIDA.md` — specifica operativa vincolante
- `docs/GDD.md` — design del gioco
- `docs/ARCHITECTURE.md` — architettura del codice
- `docs/PROTOCOL.md` — protocollo di rete
- `docs/STATE.md` — stato dei lavori
- `docs/adr/` — decisioni architetturali
+101
View File
@@ -0,0 +1,101 @@
Microsoft Visual Studio Solution File, Format Version 12.00
# Visual Studio Version 17
VisualStudioVersion = 17.0.31903.59
MinimumVisualStudioVersion = 10.0.40219.1
Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "src", "src", "{827E0CD3-B72D-47B6-A68D-7590B98EB39B}"
EndProject
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "ViaFerrea.Core", "src\ViaFerrea.Core\ViaFerrea.Core.csproj", "{D50BCC13-4F79-4DB1-BD16-5E7576006DA9}"
EndProject
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "ViaFerrea.Protocol", "src\ViaFerrea.Protocol\ViaFerrea.Protocol.csproj", "{7582B640-61C0-47F8-9A2E-B3607B01FD35}"
EndProject
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "ViaFerrea.Server", "src\ViaFerrea.Server\ViaFerrea.Server.csproj", "{D9E37057-86E8-4DDE-B3DA-EDC44F4EAE30}"
EndProject
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "ViaFerrea.Tools", "src\ViaFerrea.Tools\ViaFerrea.Tools.csproj", "{509F4E00-74B7-4FFB-84E0-3CB1F671A70E}"
EndProject
Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "tests", "tests", "{0AB3BF05-4346-4AA6-1389-037BE0695223}"
EndProject
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "ViaFerrea.Tests", "tests\ViaFerrea.Tests\ViaFerrea.Tests.csproj", "{BE4E0868-2350-4C87-968E-E424D4DEB1C5}"
EndProject
Global
GlobalSection(SolutionConfigurationPlatforms) = preSolution
Debug|Any CPU = Debug|Any CPU
Debug|x64 = Debug|x64
Debug|x86 = Debug|x86
Release|Any CPU = Release|Any CPU
Release|x64 = Release|x64
Release|x86 = Release|x86
EndGlobalSection
GlobalSection(ProjectConfigurationPlatforms) = postSolution
{D50BCC13-4F79-4DB1-BD16-5E7576006DA9}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
{D50BCC13-4F79-4DB1-BD16-5E7576006DA9}.Debug|Any CPU.Build.0 = Debug|Any CPU
{D50BCC13-4F79-4DB1-BD16-5E7576006DA9}.Debug|x64.ActiveCfg = Debug|Any CPU
{D50BCC13-4F79-4DB1-BD16-5E7576006DA9}.Debug|x64.Build.0 = Debug|Any CPU
{D50BCC13-4F79-4DB1-BD16-5E7576006DA9}.Debug|x86.ActiveCfg = Debug|Any CPU
{D50BCC13-4F79-4DB1-BD16-5E7576006DA9}.Debug|x86.Build.0 = Debug|Any CPU
{D50BCC13-4F79-4DB1-BD16-5E7576006DA9}.Release|Any CPU.ActiveCfg = Release|Any CPU
{D50BCC13-4F79-4DB1-BD16-5E7576006DA9}.Release|Any CPU.Build.0 = Release|Any CPU
{D50BCC13-4F79-4DB1-BD16-5E7576006DA9}.Release|x64.ActiveCfg = Release|Any CPU
{D50BCC13-4F79-4DB1-BD16-5E7576006DA9}.Release|x64.Build.0 = Release|Any CPU
{D50BCC13-4F79-4DB1-BD16-5E7576006DA9}.Release|x86.ActiveCfg = Release|Any CPU
{D50BCC13-4F79-4DB1-BD16-5E7576006DA9}.Release|x86.Build.0 = Release|Any CPU
{7582B640-61C0-47F8-9A2E-B3607B01FD35}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
{7582B640-61C0-47F8-9A2E-B3607B01FD35}.Debug|Any CPU.Build.0 = Debug|Any CPU
{7582B640-61C0-47F8-9A2E-B3607B01FD35}.Debug|x64.ActiveCfg = Debug|Any CPU
{7582B640-61C0-47F8-9A2E-B3607B01FD35}.Debug|x64.Build.0 = Debug|Any CPU
{7582B640-61C0-47F8-9A2E-B3607B01FD35}.Debug|x86.ActiveCfg = Debug|Any CPU
{7582B640-61C0-47F8-9A2E-B3607B01FD35}.Debug|x86.Build.0 = Debug|Any CPU
{7582B640-61C0-47F8-9A2E-B3607B01FD35}.Release|Any CPU.ActiveCfg = Release|Any CPU
{7582B640-61C0-47F8-9A2E-B3607B01FD35}.Release|Any CPU.Build.0 = Release|Any CPU
{7582B640-61C0-47F8-9A2E-B3607B01FD35}.Release|x64.ActiveCfg = Release|Any CPU
{7582B640-61C0-47F8-9A2E-B3607B01FD35}.Release|x64.Build.0 = Release|Any CPU
{7582B640-61C0-47F8-9A2E-B3607B01FD35}.Release|x86.ActiveCfg = Release|Any CPU
{7582B640-61C0-47F8-9A2E-B3607B01FD35}.Release|x86.Build.0 = Release|Any CPU
{D9E37057-86E8-4DDE-B3DA-EDC44F4EAE30}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
{D9E37057-86E8-4DDE-B3DA-EDC44F4EAE30}.Debug|Any CPU.Build.0 = Debug|Any CPU
{D9E37057-86E8-4DDE-B3DA-EDC44F4EAE30}.Debug|x64.ActiveCfg = Debug|Any CPU
{D9E37057-86E8-4DDE-B3DA-EDC44F4EAE30}.Debug|x64.Build.0 = Debug|Any CPU
{D9E37057-86E8-4DDE-B3DA-EDC44F4EAE30}.Debug|x86.ActiveCfg = Debug|Any CPU
{D9E37057-86E8-4DDE-B3DA-EDC44F4EAE30}.Debug|x86.Build.0 = Debug|Any CPU
{D9E37057-86E8-4DDE-B3DA-EDC44F4EAE30}.Release|Any CPU.ActiveCfg = Release|Any CPU
{D9E37057-86E8-4DDE-B3DA-EDC44F4EAE30}.Release|Any CPU.Build.0 = Release|Any CPU
{D9E37057-86E8-4DDE-B3DA-EDC44F4EAE30}.Release|x64.ActiveCfg = Release|Any CPU
{D9E37057-86E8-4DDE-B3DA-EDC44F4EAE30}.Release|x64.Build.0 = Release|Any CPU
{D9E37057-86E8-4DDE-B3DA-EDC44F4EAE30}.Release|x86.ActiveCfg = Release|Any CPU
{D9E37057-86E8-4DDE-B3DA-EDC44F4EAE30}.Release|x86.Build.0 = Release|Any CPU
{509F4E00-74B7-4FFB-84E0-3CB1F671A70E}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
{509F4E00-74B7-4FFB-84E0-3CB1F671A70E}.Debug|Any CPU.Build.0 = Debug|Any CPU
{509F4E00-74B7-4FFB-84E0-3CB1F671A70E}.Debug|x64.ActiveCfg = Debug|Any CPU
{509F4E00-74B7-4FFB-84E0-3CB1F671A70E}.Debug|x64.Build.0 = Debug|Any CPU
{509F4E00-74B7-4FFB-84E0-3CB1F671A70E}.Debug|x86.ActiveCfg = Debug|Any CPU
{509F4E00-74B7-4FFB-84E0-3CB1F671A70E}.Debug|x86.Build.0 = Debug|Any CPU
{509F4E00-74B7-4FFB-84E0-3CB1F671A70E}.Release|Any CPU.ActiveCfg = Release|Any CPU
{509F4E00-74B7-4FFB-84E0-3CB1F671A70E}.Release|Any CPU.Build.0 = Release|Any CPU
{509F4E00-74B7-4FFB-84E0-3CB1F671A70E}.Release|x64.ActiveCfg = Release|Any CPU
{509F4E00-74B7-4FFB-84E0-3CB1F671A70E}.Release|x64.Build.0 = Release|Any CPU
{509F4E00-74B7-4FFB-84E0-3CB1F671A70E}.Release|x86.ActiveCfg = Release|Any CPU
{509F4E00-74B7-4FFB-84E0-3CB1F671A70E}.Release|x86.Build.0 = Release|Any CPU
{BE4E0868-2350-4C87-968E-E424D4DEB1C5}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
{BE4E0868-2350-4C87-968E-E424D4DEB1C5}.Debug|Any CPU.Build.0 = Debug|Any CPU
{BE4E0868-2350-4C87-968E-E424D4DEB1C5}.Debug|x64.ActiveCfg = Debug|Any CPU
{BE4E0868-2350-4C87-968E-E424D4DEB1C5}.Debug|x64.Build.0 = Debug|Any CPU
{BE4E0868-2350-4C87-968E-E424D4DEB1C5}.Debug|x86.ActiveCfg = Debug|Any CPU
{BE4E0868-2350-4C87-968E-E424D4DEB1C5}.Debug|x86.Build.0 = Debug|Any CPU
{BE4E0868-2350-4C87-968E-E424D4DEB1C5}.Release|Any CPU.ActiveCfg = Release|Any CPU
{BE4E0868-2350-4C87-968E-E424D4DEB1C5}.Release|Any CPU.Build.0 = Release|Any CPU
{BE4E0868-2350-4C87-968E-E424D4DEB1C5}.Release|x64.ActiveCfg = Release|Any CPU
{BE4E0868-2350-4C87-968E-E424D4DEB1C5}.Release|x64.Build.0 = Release|Any CPU
{BE4E0868-2350-4C87-968E-E424D4DEB1C5}.Release|x86.ActiveCfg = Release|Any CPU
{BE4E0868-2350-4C87-968E-E424D4DEB1C5}.Release|x86.Build.0 = Release|Any CPU
EndGlobalSection
GlobalSection(SolutionProperties) = preSolution
HideSolutionNode = FALSE
EndGlobalSection
GlobalSection(NestedProjects) = preSolution
{D50BCC13-4F79-4DB1-BD16-5E7576006DA9} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B}
{7582B640-61C0-47F8-9A2E-B3607B01FD35} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B}
{D9E37057-86E8-4DDE-B3DA-EDC44F4EAE30} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B}
{509F4E00-74B7-4FFB-84E0-3CB1F671A70E} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B}
{BE4E0868-2350-4C87-968E-E424D4DEB1C5} = {0AB3BF05-4346-4AA6-1389-037BE0695223}
EndGlobalSection
EndGlobal
+94
View File
@@ -0,0 +1,94 @@
# 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`), `MapGenerator`, rumore di valore, giacimenti, `TerrainSampler`, 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`, i sistemi e il loro ordine, eventi in uscita. |
| `ViaFerrea.Core.Persistence` | `SaveWriter`/`SaveReader`, `SaveFile` (Brotli), `StateHasher`. |
## 3. Il tick
`World.Tick()` avanza di un tick (50 ms di gioco, 1/240 di giorno) e chiama i sistemi in ordine fisso:
```
Clock → Commands → Construction → Trains → Signals → Stations → Maintenance (treni)
→ Demand (giornaliero) → Commuting → Industries → IndustryMaintenance → Towns → Market
→ Finance → StockMarket → AiAgents (mensile) → Events → Contracts → Hash (giornaliero)
```
- Ogni sistema implementa `ISimSystem.Step(WorldContext ctx)`; i sistemi giornalieri o mensili controllano `ctx.IsNewDay` / `ctx.IsNewMonth` e ritornano subito negli altri tick, così il costo di un tick «vuoto» è di poche decine di nanosecondi.
- `WorldContext` espone il mondo, i dati, il calendario, i flussi `Rng` del sistema e la coda degli eventi in uscita (notifiche, avvisi, notizie) che il server traduce in messaggi.
- I comandi arrivano in una coda; il server la riempie dai socket, le IA la riempiono dal proprio sistema; il sistema `Commands` la drena a inizio tick. Per il replay si registrano `(tick, comando)`.
## 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), validazione semantica (id univoci, riferimenti risolti, limiti) in `DataValidator`.
- 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à
- Ogni movimento di denaro passa dal registro (`Ledger`) come trasferimento tra conti: compagnie, industrie, città (servizi), e il conto `Esterno` che rappresenta il resto del mondo (salari, clienti delle tariffe, mercato mondiale degli hub). La somma di tutti i saldi è sempre zero: è l'invariante «denaro» dei test.
- Ogni unità di merce sta in un deposito tracciato (magazzini delle industrie, delle stazioni, dei depositi, carichi dei treni, pacchetti) e i contatori per bene registrano prodotto, consumato, deperito, importato, esportato: totale in giacenza = prodotto + importato − consumato − deperito − esportato. È l'invariante «merci».
## 7. Salvataggi
- Formato: intestazione `VFSV`, versione del formato, versione del gioco, hash dei dati, poi il corpo compresso con Brotli.
- Il corpo è scritto con `SaveWriter` (little endian, lunghezze esplicite, nessuna reflection) componente per componente; ogni componente ha la propria versione per le migrazioni.
- Il terreno è salvato per intero (comprimibile), non rigenerato dal seme: le versioni future del generatore non devono rompere i salvataggi.
## 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`.
+73
View File
@@ -0,0 +1,73 @@
# Via Ferrea — Game Design Document
Documento di design vivo. Le regole numeriche vincolanti sono in `docs/GUIDA.md` e i valori in `data/*.json`; qui si descrive *che gioco è* e *perché* le regole sono fatte così.
## 1. Visione
«Via Ferrea» è un gestionale ferroviario visto rigorosamente dall'alto, ambientato in una regione europea immaginaria a partire dal 1850. Il giocatore guida una compagnia che costruisce binari veri (pendenze, trincee, ponti, gallerie), compra e mantiene treni, porta merci alle industrie e lavoratori ai posti di lavoro, compete con compagnie controllate dall'IA e, se vuole, le compra in borsa. Il mondo non finisce mai: regioni nuove, ere tecnologiche, decadenza delle opere e concorrenti rinnovati mantengono sempre qualcosa da fare.
Pilastri:
1. **Il territorio conta.** Ogni tracciato è un compromesso tra costo, tempo di costruzione e prestazioni: la collina si aggira, si taglia in trincea o si buca in galleria; il fiume si attraversa dove è stretto.
2. **Un'economia che si muove da sola.** Prezzi globali e locali, industrie che crescono o chiudono, città che migrano verso il servizio migliore. La ferrovia è il sistema circolatorio: dove arriva, il territorio fiorisce.
3. **Le persone sono un carico.** Ogni industria ha bisogno di lavoratori e personale qualificato che vivono in città precise e vanno portati al lavoro ogni giorno.
4. **Le macchine invecchiano.** Treni e impianti si usurano per componente; la manutenzione richiede ricambi che viaggiano in treno, depositi, personale e una politica.
5. **Leggibilità prima dell'effetto.** La mappa è una carta: impronte chiare, palette sobria, ogni numero ha un tooltip che spiega il «perché».
## 2. Ciclo di gioco
- **Minuto per minuto**: osservare i treni, intervenire su colli di bottiglia (segnali, raddoppi, locomotive), rispondere agli avvisi di manutenzione.
- **Giorno per giorno**: il resoconto giornaliero (cassa, prezzi, eventi) suggerisce opportunità: un prezzo in rialzo, un'industria senza lavoratori, un deposito senza ricambi.
- **Mese per mese**: nuove linee, nuovi treni, contratti di pendolarismo, la «Cronaca» con le notizie del mese; le IA pianificano.
- **Anno per anno**: livelli della compagnia, ere tecnologiche, rinnovi di binari e ponti, concessioni, borsa e scalate.
## 3. Tempo (convenzione del genere)
Il tempo di calendario scorre a 240 tick al giorno (12 secondi reali a velocità 1×). I treni seguono un orologio proprio, 60 volte più rapido del tempo reale: un secondo reale è un minuto di marcia. Ne segue che un viaggio di 30 minuti di orologio dura 2,5 giorni di calendario. È la stessa convenzione di Transport Tycoon e Railway Empire: il calendario serve all'economia (produzioni mensili, crescita trimestrale, ere), l'orologio dei treni serve alla fisica e agli orari. Le soglie di pendolarismo (60 minuti per i lavoratori, 90 per il personale) sono espresse in minuti di orologio dei treni.
Velocità di gioco: pausa, 1×, 2×, 4×, 8×. In multigiocatore la velocità è decisa dal server.
## 4. Mappa
- Regione quadrata di 64, 128 o 256 km con celle da 100 m, generata da un seme: colline e catene montuose con creste credibili (rumore di valore con dominio deformato), fiumi che scendono al mare allargandosi, laghi nelle conche, foreste sui pendii, paludi nelle pianure fluviali, giacimenti di carbone, ferro, pietra e petrolio con riserve finite.
- Città su pianura vicino all'acqua, a non meno di 6 km l'una dall'altra; industrie primarie sui giacimenti, di trasformazione tra materie prime e città, manifatturiere accanto alle città.
- Almeno un porto (hub verso il mercato mondiale) e un valico di frontiera.
## 5. Economia
- **Beni**: materie prime (carbone, minerale di ferro, pietra, petrolio, tronchi, grano, bestiame), semilavorati (acciaio, legname, carburante, materiali edili), prodotti finiti (alimentari, merci varie, attrezzi) e beni di servizio (ricambi e macchinari) indispensabili alla manutenzione.
- **Prezzi**: ogni bene ha un prezzo globale che reagisce lentamente al rapporto tra domanda e offerta della regione e a un ciclo mondiale con shock; ogni nodo ha un prezzo locale entro ±40 % del globale secondo lo squilibrio locale. Gli hub comprano e vendono al prezzo mondiale con un dazio.
- **Industrie**: producono secondo la copertura minima tra input, lavoratori e personale, corretta dal margine economico e dalla condizione degli impianti. Crescono di livello se servite bene, regrediscono e chiudono se abbandonate; dove un bene resta insoddisfatto a lungo ne nasce una nuova.
- **Città**: crescono con la soddisfazione (beni consegnati rispetto alla domanda) e l'occupazione; chi è mal servito emigra verso città meglio collegate.
- **Compagnia**: incassa tariffe per merci e passeggeri (in funzione di distanza, prezzo del bene e puntualità), paga costruzione, manutenzione, personale e interessi. Rating di credito, prestiti, livelli che sbloccano strumenti (squadre di cantiere, commercio, acquisto di industrie, borsa, scalate, concessioni).
## 6. Costruzione
Il giocatore traccia una polilinea; il motore campiona il terreno ogni 25 m, calcola il profilo con il minimo movimento terra che rispetta la pendenza massima della trazione e classifica ogni tratto come sede naturale, rilevato, trincea, ponte o galleria. Ogni opera ha costo e tempo; le squadre di cantiere costruiscono in ordine lungo la linea. Le ere sbloccano ponti più lunghi e gallerie più profonde. L'anteprima nel client usa le stesse classi del server e mostra il grafico del profilo prima della conferma.
## 7. Pendolarismo
Ogni città ha una forza lavoro (40 % degli abitanti) e, se abbastanza grande e servita, personale qualificato (8 %). Ogni mese l'abbinatore crea contratti casa-lavoro sui percorsi della rete entro i tempi massimi; ogni giorno i contratti generano pacchetti di passeggeri e il vettore incassa per ogni tratta completata. La copertura dei posti di lavoro entra direttamente nell'efficienza delle industrie e nella velocità delle officine della compagnia. Il tratto a piedi è ammesso solo dentro il bacino di una stazione o tra città e posto di lavoro vicinissimi.
## 8. Manutenzione
Treni e industrie si usurano per componente. Il pianificatore predittivo manda i treni in deposito prima che un componente scenda sotto la soglia, scegliendo il deposito con ricambi e stalli liberi. Senza ricambi (che arrivano solo in treno) gli interventi aspettano e i guasti crescono; senza personale qualificato le officine rallentano. Le industrie non rifornite di ricambi e macchinari decadono: chi trasporta ricambi controlla la salute del territorio.
## 9. Concorrenza e finanza
Le compagnie IA giocano con gli stessi comandi e gli stessi vincoli del giocatore, con personalità diverse (espansiva, prudente, predatoria). Ogni compagnia ha un milione di azioni; quotazione, dividendi, scalate ostili e difese (riacquisto, dividendo straordinario, cavaliere bianco). Se il giocatore viene comprato, la difficoltà decide se continua in amministrazione controllata o se la partita finisce con la «Cronaca finale».
## 10. Gioco infinito
Regioni acquistabili ai bordi, ere senza fine con generazioni di veicoli, decadenza e rinnovo di ogni opera, giacimenti che si esauriscono, concorrenti finanziati dallo stato e antitrust, bandi e grandi opere, prestigio e dinastia, modalità holding e Nuova partita+. Lo stato «ho comprato tutto» non è stabile: il mondo lo erode.
## 11. Difficoltà
Quattro preset (Apprendista, Imprenditore, Magnate, Ferro e sangue) più Personalizzata. La difficoltà cambia capitale, credito, costi, tariffe, usura, volatilità, numero e forza delle IA, regole di scalata e bancarotta; non cambia mai i vincoli fisici.
## 12. Presentazione
- Vista dall'alto, nessuna prospettiva (immagini `reference/01`–`05`).
- Interfaccia scura blu-ardesia con un solo accento ambra; mappa chiara cartografica.
- Titoli in Big Shoulders Display 800, testo e numeri in IBM Plex Sans con cifre tabulari, separatore delle migliaia con punto e decimali con virgola (₤ 1.284.500).
- Testi in italiano con localizzazione inglese.
+359
View File
@@ -0,0 +1,359 @@
# VIA FERREA — Guida operativa per Claude Code (v2)
Sei lo sviluppatore principale di «Via Ferrea», gestionale ferroviario dall'alto per desktop, con motore di gioco headless eseguibile anche su un server Linux in Docker. Questo documento sostituisce la v1 e ti dice esattamente cosa costruire, con quale linguaggio, in quale ordine e come verificarlo. Le nove immagini in `reference/` (01–09) sono il riferimento visivo vincolante. Non chiedere conferme: se manca un dettaglio, decidi, scrivi un ADR in `docs/adr/` e vai avanti. Salva questo file come `docs/GUIDA.md` nella prima sessione.
---
## 0. Regole di lavoro
- Una fase alla volta, nell'ordine della sezione 16. Ogni fase termina con build verde, test verdi, `docs/STATE.md` aggiornato e un commit `F<n>: <cosa>`.
- Zero pacchetti NuGet in tutti i progetti .NET, test compresi. ASP.NET Core si usa solo come shared framework (`Sdk="Microsoft.NET.Sdk.Web"`). `scripts/check-nuget.sh` fa fallire la build se compare un `PackageReference`.
- Unica dipendenza esterna ammessa: il motore Godot per il client.
- Identificatori in inglese; commenti, documentazione e testi UI in italiano (localizzazione it/en in `client/assets/i18n/`).
- Nessun numero magico: ogni parametro sta in `data/*.json`. Le costanti citate qui sono i valori iniziali di quei file.
- Ogni decisione non coperta qui → `docs/adr/NNNN-titolo.md` (contesto, decisione, conseguenze).
- Il client non contiene logica di gioco: calcola solo anteprime usando le stesse classi di `ViaFerrea.Core`; il server è sempre autorevole.
## 1. Piattaforma e linguaggio (decisioni fisse)
- Linguaggio: C# 14 su .NET 10 per core, protocollo, server, strumenti e test.
- Server: ASP.NET Core minimal hosting (Kestrel), Linux x64 in Docker; gira anche su Windows come processo locale figlio del client.
- Client: Godot 4 versione .NET (ultima stabile), rendering 2D dall'alto, export Windows x64 (Linux opzionale).
- Rete: WebSocket con frame binari custom. JSON (System.Text.Json con source generator) solo per file dati, configurazione e dump di debug.
- Denaro: `long` in centesimi. Tempo: tick fisso da 50 ms di gioco.
- Salvataggi: snapshot binari compressi con Brotli (`System.IO.Compression`), portabili tra Windows e Linux.
## 2. Prerequisiti (verificali e annota le versioni in docs/STATE.md)
- `dotnet --version` → 10.x. Se manca, fermati e scrivilo nel riepilogo.
- Godot 4 .NET: eseguibile stabile più recente in PATH come `godot`; verifica con `godot --version`.
- Docker (dalla Fase 3): `docker --version`.
- Git configurato con remote su Gitea.
## 3. Creazione della soluzione (esegui esattamente questi comandi)
```
dotnet new sln -n ViaFerrea
dotnet new classlib -n ViaFerrea.Core -o src/ViaFerrea.Core -f net10.0
dotnet new classlib -n ViaFerrea.Protocol -o src/ViaFerrea.Protocol -f net10.0
dotnet new web -n ViaFerrea.Server -o src/ViaFerrea.Server -f net10.0
dotnet new console -n ViaFerrea.Tools -o src/ViaFerrea.Tools -f net10.0
dotnet new console -n ViaFerrea.Tests -o tests/ViaFerrea.Tests -f net10.0
dotnet sln add src/ViaFerrea.Core src/ViaFerrea.Protocol src/ViaFerrea.Server src/ViaFerrea.Tools tests/ViaFerrea.Tests
dotnet add src/ViaFerrea.Protocol reference src/ViaFerrea.Core
dotnet add src/ViaFerrea.Server reference src/ViaFerrea.Core src/ViaFerrea.Protocol
dotnet add src/ViaFerrea.Tools reference src/ViaFerrea.Core src/ViaFerrea.Protocol
dotnet add tests/ViaFerrea.Tests reference src/ViaFerrea.Core src/ViaFerrea.Protocol src/ViaFerrea.Server
```
- `Directory.Build.props` alla radice: `Nullable=enable`, `ImplicitUsings=enable`, `LangVersion=latest`, `TreatWarningsAsErrors=true`, `InvariantGlobalization=true`, `Deterministic=true`, `Version` (unica fonte della versione).
- Core e Protocol: `<TargetFrameworks>net10.0;net8.0</TargetFrameworks>` (il progetto Godot può richiedere net8.0 o net9.0: verifica il TargetFramework generato da Godot e allinea).
- Client (Fase 3): `client/ViaFerrea.Client` con `project.godot`; il csproj lo genera Godot (Project › Tools › C# › Create C# solution) oppure scrivilo a mano con `<Project Sdk="Godot.NET.Sdk/<versione Godot>">`, `EnableDynamicLoading=true` e `ProjectReference` a Core e Protocol. Il client non entra nella sln principale.
- Struttura finale:
```
CLAUDE.md README.md Directory.Build.props ViaFerrea.sln
docs/ GDD.md ARCHITECTURE.md PROTOCOL.md GUIDA.md STATE.md adr/
data/ goods.json industries.json vehicles.json eras.json tiers.json balance.json
difficulty.json construction.json maintenance.json ai.json contracts.json regions.json schema/
src/ ViaFerrea.Core ViaFerrea.Protocol ViaFerrea.Server ViaFerrea.Tools
client/ ViaFerrea.Client (scenes/ scripts/ assets/fonts/ assets/i18n/ assets/theme/)
tests/ ViaFerrea.Tests (scenarios/)
docker/ Dockerfile docker-compose.yml unraid-template.xml
scripts/ build.sh build.ps1 test.sh check-nuget.sh publish-image.sh
reference/ 01..09 .jpg
```
## 4. Convenzioni di codice
- Identità tipizzate: `readonly record struct StationId(int Value)` e simili per Town, Industry, Hub, Node, Edge, Signal, Train, Vehicle, Line, Company, Packet, Contract, Depot, Region.
- `readonly record struct Money(long Cents)` con operatori, `Money.FromLire(decimal)`, `ToString("it")`.
- PRNG interno xoshiro256** (`Rng`), uno per sottosistema via `world.Rng.Fork("industries")`; vietati `Random`, `Guid.NewGuid`, `DateTime.Now`, `Environment.TickCount` nella simulazione.
- Stato in array e `List` ordinati per id; mai iterare `Dictionary`/`HashSet` per produrre effetti; dizionari solo come indici di lookup.
- Nessuna allocazione nel ciclo di tick per treni e pacchetti (struct, pooling, `Span`).
- Ogni sistema espone `void Step(WorldContext ctx)`, chiamato da `World.Tick()` in ordine fisso:
Clock → Commands → Construction → Trains → Signals → Stations → Maintenance (treni) → Demand (una volta al giorno) → Commuting → Industries → IndustryMaintenance → Towns → Market → Finance → StockMarket → AiAgents (una volta al mese) → Events → Contracts → Hash (una volta al giorno).
## 5. File dati e schemi
Tutti i file hanno uno schema in `data/schema/` e sono validati all'avvio del server e da `viaferrea-tools validate-data` (id univoci, riferimenti risolti, limiti).
- `goods.json`: `{ "id":"coal", "name_it":"Carbone", "category":"bulk|general|liquid|perishable", "unit":"t", "wagon":"hopper", "basePrice":3800, "elasticity":0.6, "decayDaysAtStation":20, "era":1850 }`. Includi i beni di servizio `spare_parts` (ricambi, prodotti dalla fabbrica di macchinari) e `machinery` (macchinari): la manutenzione li consuma e arrivano solo in treno.
- `industries.json`: `{ "id":"steel_mill", "name_it":"Acciaieria", "kind":"primary|processing|manufacturing", "recipe":{ "inputs":[{"good":"iron_ore","perCycle":2},{"good":"coal","perCycle":1}], "outputs":[{"good":"steel","perCycle":1}] }, "cycleDays":1, "capacityPerLevel":[120,240,400,600,900], "workersPerLevel":[40,80,160,240,320], "staffPerLevel":[2,6,12,20,30], "storageDays":30, "wearIntensity":1.2, "footprint":"large", "placement":{ "needs":"ore_deposit|forest|plain|coast|any", "minTownDistanceKm":2 }, "depletable":true, "era":1850 }`.
- `vehicles.json`: locomotive `{ "id":"loco_steam_1850", "kind":"locomotive", "name_it":"Ardita 2-6-0", "eraFrom":1850, "eraTo":1905, "powerKw":300, "tractiveEffortKn":45, "maxSpeedKmh":60, "massT":38, "lengthM":11, "price":1800000, "lifeYears":25, "traction":"steam|diesel|electric", "components":{ "engine":1.0, "wheelsets":0.8, "brakes":1.0, "electrics":0.6 } }` (moltiplicatori di usura per componente); carri `"kind":"wagon", "capacity":20, "wagonType":"hopper|flat|tank|box", "goods":[...]`; carrozze `"kind":"coach", "paxCapacity":40, "class":"worker|staff"`.
- `eras.json`: anni di introduzione di trazioni, tipi di ponte, lunghezza massima gallerie, classi di velocità del binario, segnali.
- `tiers.json`: cinque livelli con `requirements` (netWorth, connectedTownsOver, creditRating) e `unlocks` (maxLoan, crews, trading, buyIndustry, ipo, hostileTakeover, concessions).
- `balance.json`: costanti delle formule (sezioni 6–11).
- `difficulty.json`, `construction.json`, `maintenance.json`, `ai.json`, `contracts.json`, `regions.json`: vedi le sezioni dedicate.
## 6. Core: tempo, mappa, economia
### 6.1 Tempo
- `GameClock`: tick 50 ms; 240 tick = 1 giorno di calendario (12 s reali a 1×); mesi di 30 giorni, anno di 360 giorni; velocità 0/1/2/4/8 gestita dal server.
- Moto dei treni: 1 secondo reale a 1× = 1 minuto di orologio dei treni (fattore 60). Un viaggio di 30 minuti di orologio dura 2,5 giorni di calendario: convenzione del genere, documentata nel GDD.
### 6.2 Mappa e terreno
- Cella 100 m; mappa 64/128/256 km → 640/1280/2560 celle per lato; altezze in `ushort` (metri × 10), tipo cella in `byte` (plain, hill, mountain, forest, field, water, sea, town, industry, rock, marsh).
- Generazione da seed: rumore di valore a 5 ottave (implementato in Core) per l'altimetria con dominio deformato (domain warping) per creste e valli credibili; mare = celle sotto quota 0 collegate a un bordo; fiumi = discesa dal 30° percentile fino al mare con carving e larghezza crescente (1–4 celle); laghi nelle conche chiuse; foreste su pendii medi; roccia sopra il 70° percentile; paludi vicino ai fiumi in pianura; giacimenti (carbone, ferro, pietra, petrolio) come cluster con riserva in tonnellate.
- Città: 8–60 secondo la dimensione, su pianura vicino ad acqua, distanza minima 6 km; industrie primarie sui giacimenti, di trasformazione entro 12 km da input e città, manifatturiere accanto alle città; almeno un porto e un valico.
- `TerrainSampler`: altezza bilineare in un punto qualsiasi (metri); `Slope(x,y)` e `Aspect` per l'ombreggiatura; curve di livello ogni 20 m calcolate dal client.
- Chunk 64×64 celle per trasmissione e rendering.
### 6.3 Economia
- Prezzo globale, ogni giorno: `Pg' = clamp(Pg × (1 + k·(D/S − 1)), 0.3·Pb, 3·Pb)`, `Pg = α·Pg' + (1−α)·Pg`; D e S = domanda e offerta degli ultimi 30 giorni più la componente mondiale `W(t) = Pb·(A·sin(2πt/T) + shock)`. Iniziali: k=0.08, α=0.15, A=0.12, T=6 anni.
- Prezzo locale al nodo: `Pl = Pg × (1 + λ·(Dl − Sl)/(Dl + Sl + ε))`, λ=0.35, entro ±40 %.
- Industria, ogni giorno: `e = min(covInput, covWorkers, covStaff) × pf × mc`, coperture su finestra di 30 giorni, `pf = clamp(1 + 0.5·margine, 0.6, 1.2)`, `mc` = moltiplicatore di condizione degli impianti (sezione 11); produzione = capacità(livello)·e/30; consumo input proporzionale; oltre `storageDays` l'output si perde.
- Giacimenti esauribili: ogni miniera/pozzo ha una riserva; sotto il 20 % la capacità cala linearmente; a zero chiude; la prospezione (sezione 12) scopre nuovi giacimenti.
- Crescita trimestrale: `score = 0.5·quotaTrasportata + 0.3·coperturaMedia + 0.2·redditività`; > 0.75 per due trimestri → livello+1 (max 5); < 0.35 → livello−1; livello 0 per quattro trimestri → chiusura. Nuova industria dove un bene resta insoddisfatto per un anno.
- Città, ogni mese: `g = 0.002 + 0.004·(soddisfazione − 0.5) + 0.003·(occupati/popolazione − 0.4)`, clamp ±0.01; soddisfazione per categoria = EMA di min(1, consegnato/domanda). Forza lavoro = 40 % della popolazione; personale qualificato = 8 % se popolazione ≥ 5.000 e servizi ≥ 2. Migrazione: ogni anno l'1 % della popolazione delle città con soddisfazione < 0.4 si sposta nelle città meglio servite raggiungibili.
- Hub: capacità mensile e dazio; comprano e vendono a `Pg × (1 ± dazio)`.
- Tariffe (vettore): merci `units × baseRate × (0.6 + 0.4·Pg/Pb) × km^0.9 × tf`; passeggeri `pax × baseFare × km^0.85 × classe` (worker 1, staff 3); `tf` scende da 1 a 0.5 se la consegna supera del 50 % il tempo atteso.
- Finanza: cassa, prestiti (tasso = base + spread per rating), manutenzione, stipendi, interessi; rating da (utile/ricavi, debito/patrimonio); bancarotta con cassa < 0 per i giorni previsti dalla difficoltà; patrimonio netto = attivo a valore di libro − debiti.
## 7. Difficoltà (`data/difficulty.json`)
Quattro preset più «Personalizzata» (ogni parametro modificabile alla creazione della partita e mostrato nel riepilogo).
| Parametro | Apprendista | Imprenditore | Magnate | Ferro e sangue |
|---|---|---|---|---|
| Capitale iniziale (₤) | 500.000 | 250.000 | 150.000 | 100.000 |
| Fido iniziale (₤) | 500.000 | 300.000 | 150.000 | 100.000 |
| Tasso base prestiti | 3 % | 5 % | 7 % | 9 % |
| Costi di costruzione | ×0.8 | ×1.0 | ×1.25 | ×1.5 |
| Tariffe | ×1.15 | ×1.0 | ×0.9 | ×0.8 |
| Usura e guasti | ×0.7 | ×1.0 | ×1.3 | ×1.6 |
| Volatilità di mercato (A, shock) | ×0.6 | ×1.0 | ×1.3 | ×1.6 |
| Concorrenti IA | 1 | 2 | 3 | 5 |
| Capitale IA | ×0.7 | ×1.0 | ×1.5 | ×2.0 |
| Sconto costi IA | 0 % | 0 % | 10 % | 20 % |
| Scalata ostile del giocatore | disattivata | con riscatto (3 anni) | con riscatto (1 anno) | immediata |
| Giorni di cassa negativa prima della bancarotta | 180 | 90 | 60 | 30 |
| Compagnia quotata dall'inizio | no | no | no | sì (60 % al giocatore) |
| Ironman (un solo salvataggio, niente ricarica) | no | opzionale | opzionale | sì |
| Esaurimento giacimenti | lento | normale | veloce | veloce |
I vincoli fisici (pendenze, raggi, campate, gallerie) non cambiano con la difficoltà: cambiano costi, tempi e rischi.
## 8. Costruzione realistica dei binari (stile Railway Empire)
`data/construction.json` contiene tutti i valori qui citati.
### 8.1 Profilo altimetrico e opere
- L'utente traccia la polilinea (snap a 45°, curve con raggio scelto dalla classe di velocità). Core campiona il terreno ogni 25 m lungo la linea: `hTerreno[i]`.
- Profilo del binario `hBinario[i]`: parte da `hTerreno` più lo scostamento scelto dall'utente (cursore ±20 m), poi due passate di limitazione della pendenza (avanti e indietro: `h[i] = min(h[i], h[i−1] + gMax·25)`), poi smussatura a finestra di 5 campioni. Risultato: il profilo con meno movimento terra che rispetta `gMax`.
- Classificazione per campione con `d = hBinario − hTerreno`:
- |d| ≤ 1,5 m → sede naturale;
- 1,5 < d ≤ 8 m → rilevato; −8 ≤ d < −1,5 m → trincea;
- d > 8 m, oppure cella d'acqua o palude → ponte/viadotto (luce libera minima 6 m sopra i fiumi, 12 m sopra le vie navigabili);
- d < −8 m → galleria.
- Campioni contigui dello stesso tipo si fondono in `Work { Kind, StartM, EndM, MaxHeight, CostCents, Days }`.
- Costo per metro = base × moltiplicatore classe binario × modificatore terreno (roccia ×1.8, palude ×1.6) × difficoltà, con: sede naturale ×1; rilevato ×(1 + 0.25·d); trincea ×(1 + 0.35·d); ponte ×(6 + 0.5·d); galleria ×12. Più il costo del terreno per cella (×3 entro 2 km dalle città, ×2 sui campi).
- Vincoli per era (`eras.json`): campata massima dei ponti (legno 60 m dal 1850, ferro 150 m dal 1870, acciaio 400 m dal 1900, cemento 800 m dal 1950); lunghezza massima galleria (1 km dal 1850, 5 km dal 1900, 15 km dal 1950); un fiume più largo della campata massima si attraversa solo dove è più stretto.
- Pendenza massima `gMax` per trazione: vapore 2,5 %, diesel 3,5 %, elettrico 4 %, alta velocità 3,5 %. Un tracciato più ripido della locomotiva assegnata riceve avviso e la linea richiede doppia trazione.
- Raggio minimo per classe di velocità: 60 km/h → 200 m; 100 → 400 m; 160 → 900 m; 250 → 2.500 m. Velocità in curva `vMax = min(vClasse, 3.6·sqrt(0.65·R))` km/h.
- Divieti: attraversare impronte di città, industrie, stazioni altrui; incrociare a raso binari altrui (serve un cavalcavia: ponte automatico).
### 8.2 Cantieri e tempi
- Le opere si costruiscono in ordine lungo la linea da squadre (`Crew`): 200 m/giorno sede naturale, 60 m/giorno trincea e rilevato, 20 m/giorno ponte, 8 m/giorno galleria. Squadre disponibili per livello: 2/4/8/12/20. Il binario è `UnderConstruction` finché l'ultima opera non è finita; treni esclusi.
- Anteprima nel client (calcolata con Core su chunk già scaricati): grafico del profilo (terreno e binario), opere colorate, costo per opera, giorni, pendenza massima, raggio minimo, avvisi. Verde = valida, rossa = motivo del rifiuto. Il server ricalcola e rifiuta se il risultato differisce.
- Classi di binario: 60/100/160/250 km/h con costo ×1/1.4/2.2/4; singolo o doppio; elettrificato (+35 %). L'ammodernamento chiude la tratta per i giorni delle opere.
### 8.3 Usura del binario
- Condizione 0–100 per arco; usura giornaliera `= tonnellate·(1 + 8·pendenza)·(1 + 0.4·velocità/vMax) / K` con K in `construction.json`; manutenzione ordinaria per km/giorno mantiene −0.02/giorno di deriva; condizione < 60 → limite 60 % della classe; < 30 → 30 % e rischio guasto; rinnovo = 40 % del costo di costruzione, 3 giorni/km di chiusura.
- Ponti e gallerie hanno una condizione propria con ispezioni annuali obbligatorie (costo) e rinnovo ogni 50 anni: senza rinnovo, limite di velocità e poi chiusura.
### 8.4 Effetti sulla marcia
- `a = (Ft(v) − R(v, i)) / m`, `Ft = min(P/v, adesione·massaLoco·g·0.3)`, `R = m·g·(0.0015 + i) + 0.6·v²·cx`; frenata 0,5 m/s²; velocità limitata da classe dell'arco, curva, condizione, veicolo. Un treno che non supera una salita resta in `Stalled` e genera un avviso: aggiungere locomotiva o cambiare tracciato.
## 9. Sistema del pendolarismo (lavoratori e personale)
Obiettivo: ogni lavoratore ha una casa e un posto di lavoro precisi e raggiunge l'industria con i treni del giocatore (o dei concorrenti).
- Ogni città ha `LaborPool { Workers, Staff, Employed }`; ogni industria e ogni deposito hanno `Jobs { Workers, Staff }` per livello; le città stesse offrono posti (servizi) per una quota della popolazione.
- Ogni mese `EmploymentMatcher` costruisce i `CommuteContract { Town, Workplace, Category, Headcount, HomeStation, WorkStation, Route (linee e cambi), ExpectedMinutes, Carrier }`:
1. per ogni posto scoperto cerca città con lavoratori liberi raggiungibili sul `LineGraph` entro 60 minuti di orologio treni (personale: 90 minuti, solo città con servizi), includendo il tratto a piedi dentro il bacino;
2. ordina per tempo di viaggio; assegna in proporzione ai lavoratori liberi, non oltre la capacità residua stimata delle linee (posti per giorno);
3. i contratti esistenti restano validi se il percorso esiste ancora.
- Ogni giorno ogni contratto genera pacchetti passeggeri: andata (Headcount, da HomeStation a WorkStation, scadenza 2 giorni) e ritorno (generato all'arrivo). Il vettore incassa la tariffa per ogni tratta completata.
- Copertura del posto di lavoro = EMA di (consegnati/Headcount) su 30 giorni; entra in `covWorkers`/`covStaff` dell'industria. Copertura < 0.5 per 90 giorni → il contratto si scioglie (i lavoratori tornano liberi) e la città registra insoddisfazione «lavoro».
- Convenzioni: un'industria può proporre al vettore un `CommuteAgreement` (canone mensile in cambio di capacità garantita: posti/giorno); se la capacità manca per 30 giorni la convenzione salta con penale. Il giocatore le vede nel «Registro degli impieghi» e le accetta o rifiuta.
- Le strutture della compagnia (depositi e officine) hanno posti per personale qualificato: senza personale consegnato la manutenzione rallenta (sezione 10).
- UI: pannello industria mostra provenienza dei lavoratori per città e linea, posti scoperti e motivo («nessuna città raggiungibile entro 60 min», «capacità delle carrozze insufficiente sulla Linea 1», «città senza servizi per il personale»); pannello città mostra dove lavorano i suoi abitanti; mappa con flussi opzionali (frecce blu).
## 10. Manutenzione avanzata dei treni (`data/maintenance.json`)
Sistema dedicato `FleetMaintenanceSystem`, con simulazione per componente.
### 10.1 Modello di usura
- Componenti della locomotiva con peso di guasto: motore o caldaia 0.40, rodiggio e assali 0.25, freni 0.20, impianto elettrico o trasmissione 0.15. Carri e carrozze: assali 0.5, freni 0.3, cassa 0.2. Ogni componente ha condizione `c` 0–100.
- Usura giornaliera per componente: `w = wBase × (kmGiorno/100) × (1 + 2·quotaPendenza) × (1 + 0.5·quotaAltaVelocità) × (1 + 0.3·carico) × ageFactor × difficoltà`, con `wBase` per componente (motore 0.25 per 100 km: da 100 a 0 in 40.000 km senza manutenzione), `quotaPendenza` = quota di km su pendenze > 1,5 %, `quotaAltaVelocità` = quota di km sopra l'80 % della velocità massima, `ageFactor = 1` fino a `lifeYears`, +0.5 ogni 5 anni oltre.
- Rischio di guasto giornaliero: `h = h0 × exp(0.8·(50 − c)/10)` se `c < 50`, altrimenti `h0/4`, con `h0 = 0.002`; il componente con `h` più alto determina il tipo: lieve 70 % (velocità dimezzata fino al deposito), grave 27 % (fermo in linea: blocca il binario finché arriva la squadra di soccorso dal deposito più vicino, tempo = distanza/40 km/h + 2 ore, oppure una locomotiva di riserva), catastrofico 3 % solo se `c < 15` e `v > 0.8·vMax` (deragliamento: veicoli distrutti, binario danneggiato per 3 giorni, carico perso, notizia negativa, soddisfazione −).
- Effetti della condizione: velocità massima ×(0.6 + 0.4·cMotore/100) se `cMotore < 70`; consumo ×(1 + 0.4·(1 − cMotore/100)); comfort delle carrozze = cCassa, che modula tariffa e soddisfazione passeggeri (×0.8..1.05); valore di rivendita = prezzo × (età/vita) × condizione media.
### 10.2 Interventi
| Intervento | Durata | Effetto | Costo | Ricambi |
|---|---|---|---|---|
| Ispezione | 1 giorno | freni 100, altri +10, azzera i difetti nascosti (h ×0.5 per 30 giorni) | 0,5 % del prezzo | 0 |
| Tagliando | 3 giorni | ogni componente min(100, c + 40) | 3 % del prezzo | 1 |
| Revisione generale | 20 giorni | tutto a 100, ageFactor ridotto di 0.5 (min 1) | 25 % del prezzo | 5 |
| Riparazione dopo guasto lieve / grave / catastrofico | 2 / 7 / 30 giorni | componente guasto a 80 / 90 / veicolo sostituito | 5 / 15 / 40 % del prezzo | 1 / 3 / 8 |
- I ricambi sono il bene `spare_parts`: ogni deposito ha una scorta; se manca, l'intervento aspetta; i ricambi arrivano solo in treno da una fabbrica di macchinari o da un hub di importazione (il giocatore deve organizzare la linea di rifornimento dei propri depositi).
- Deposito: 2/4/8 stalli per dimensione; ogni stallo richiede 4 unità di personale qualificato in servizio (pendolarismo, sezione 9): con personale al 50 % le durate raddoppiano.
- Politica di servizio (per flotta, con override per linea o treno): Economica (intervalli ×1.5, effetti ×0.7, costi ×0.6), Standard, Accurata (intervalli ×0.7, effetti ×1.2, costi ×1.6). Intervalli base: ispezione ogni 3.000 km o 45 giorni; tagliando ogni 15.000 km o 180 giorni; revisione ogni 6 anni.
### 10.3 Pianificatore predittivo
- Ogni giorno, per ogni treno: stima i giorni al raggiungimento di `c = 40` per ciascun componente con l'usura media degli ultimi 15 giorni; `dueDate = min(scadenza da politica, stima − 5 giorni)`.
- Sceglie il deposito con `tempoViaggio + attesaStimata` minima tra quelli con ricambi sufficienti; prenota lo stallo; inserisce l'ordine «vai in deposito» dopo la fermata corrente; a fine intervento riprende la linea.
- Treni di riserva: il giocatore può marcare treni come «riserva» in deposito; il pianificatore li usa per coprire la linea durante gli interventi lunghi.
- UI: «Cartella di manutenzione» per treno (indicatori per componente, storico, prossimo intervento, costi dell'anno), vista flotta con mappa di calore della condizione, avvisi («Treno 12: freni al 35 %, ispezione entro 4 giorni», «Deposito di Valdoria: ricambi esauriti»), «Registro officina» con la coda degli stalli.
## 11. Manutenzione avanzata delle industrie (`IndustryMaintenanceSystem`)
- Ogni industria ha condizione impianti `c` 0–100. Usura giornaliera `= 0.06 × utilizzo × wearIntensity × difficoltà` (a pieno regime senza manutenzione: da 100 a 0 in circa 4,5 anni).
- Moltiplicatore di efficienza `mc = 1` per `c ≥ 70`, lineare fino a 0.5 per `c = 20`, 0.3 sotto.
- Rischio di fermo giornaliero `= 0.001 × exp((40 − c)/8)` per `c < 40`: fermo di 5–20 giorni, notizia, soddisfazione della città −2 %. Incidente grave (c < 10 e industria di trasformazione): fermo 60 giorni, popolazione −0,2 %.
- Politiche del proprietario (NPC o giocatore): budget Nessuno / Base / Alto → recupero giornaliero 0 / 0.05 / 0.12 punti, costo 0 / 3 / 7 % dei ricavi, consumo mensile di `spare_parts` 0 / 1 / 3 unità per livello (senza ricambi il recupero si dimezza).
- Fermo programmato (revisione): 30 giorni di fermo, richiede `machinery` (2 unità per livello) e copertura del personale ≥ 0.8; riporta `c` a 100.
- Ammodernamento di livello: costo capitale + `machinery` (5 unità per livello) + 60 giorni; NPC lo fanno solo con margine > 15 % per due anni e ricambi disponibili.
- IA del proprietario NPC: budget Base; margine > 15 % → Alto; margine < 0 → Nessuno; revisione quando `c < 35` e cassa sufficiente. Un'industria non servita dai ricambi decade e chiude: chi trasporta ricambi e macchinari controlla la salute del territorio.
- Industrie del giocatore: pannello con condizione, politica, scorta ricambi, storico fermi, pulsanti «Fermo programmato», «Ammoderna», «Ordina ricambi» (crea domanda esplicita sul LineGraph con priorità).
## 12. Concorrenti IA, borsa e scalate
### 12.1 Agenti (`data/ai.json`)
- `AiCompanyAgent` usa esclusivamente i comandi del protocollo (nessun accesso privilegiato allo stato). Pianificazione mensile:
1. genera candidati: coppie (sorgente, destinazione) non servite con margine stimato dagli stessi estimatori disponibili nei tooltip; città senza stazione; industrie con posti scoperti;
2. per ogni candidato stima costo di costruzione con `TrackPlanner` su un percorso trovato con Dijkstra sulla griglia delle celle (costo = costo di costruzione della cella + penalità pendenza), ricavi annui, ROI;
3. esegue i progetti con ROI sopra la soglia della personalità finché cassa e fido lo consentono; compra treni, imposta politiche di manutenzione Standard, prende prestiti, acquista industrie e azioni quando il livello lo sblocca.
- Personalità: Espansiva (soglia ROI 8 %, prestiti fino all'80 % del fido), Prudente (ROI 15 %, prestiti 30 %), Predatoria (ROI 10 %, punta ai mercati del giocatore e compra azioni altrui appena può).
- Vincoli identici al giocatore: costruzione realistica, manutenzione, pendolarismo. Bonus solo da `difficulty.json` (capitale, sconto costi).
- Le IA possono fallire: liquidazione, asset all'asta (il giocatore può comprarli), nuovi concorrenti entrano quando la concentrazione di mercato supera il 60 % (sezione 13).
### 12.2 Borsa
- Ogni compagnia ha 1.000.000 di azioni. Prezzo = `max(patrimonioNetto, 8 × utile annuo) / azioni × sentiment`, `sentiment` 0.8–1.3 da crescita degli utili e ciclo di mercato; scambi giornalieri con spread 1 %.
- Il giocatore parte privato (100 % proprie) salvo difficoltà «Ferro e sangue». Quotazione (livello 4): emette fino al 40 % di azioni e incassa capitale; dividendi trimestrali facoltativi (alzano il sentiment).
- Chi possiede > 50 % controlla: la controllata versa gli utili al controllante, che dopo un anno può fonderla. Scalata ostile (livello 5 o IA con cassa): `Offerta { premio 20–50 %, durata 90 giorni }` sulle azioni sul mercato; il bersaglio può rispondere con riacquisto proprio (fino alla cassa disponibile), dividendo straordinario (rende il titolo più caro) o «cavaliere bianco» (un'altra compagnia alleata compra il flottante).
### 12.3 Se l'IA compra il giocatore
- Via borsa (solo se quotato) o via insolvenza (creditori vendono la compagnia al miglior offerente dopo i giorni di cassa negativa della difficoltà).
- Esito per difficoltà: Apprendista → mai; Imprenditore → «Amministrazione controllata»: il giocatore continua con dividendo obbligatorio del 50 %, senza nuovi prestiti, e ha 3 anni per riacquistare il 51 % (le azioni restano scambiabili); Magnate → 1 anno; Ferro e sangue → fine immediata.
- Fine partita: schermata «Cronaca finale» (storia della compagnia, grafici, record, prestigio) con opzione «Continua come osservatore» (mondo che va avanti, IA che giocano) e «Nuova partita+» (sezione 13).
## 13. Gioco infinito (nessuna fine, anche dopo aver comprato tutto)
Implementa questi sistemi come `EndlessSystems`, attivabili singolarmente alla creazione della partita (default: tutti attivi tranne la dinastia).
1. **Regioni e concessioni**: la mappa non finisce. Ai bordi ci sono regioni non ancora generate (`regions.json`: clima, risorse, difficoltà del terreno, hub). Al livello 3 il giocatore può comprare una concessione (prezzo crescente) che genera la regione con lo stesso seed e la collega con un valico; i chunk si aggiungono al mondo e ai salvataggi. Nuove regioni portano risorse mancanti e mercati nuovi; il mondo cresce finché il giocatore vuole (limite tecnico: 16 regioni, poi «continente pieno» con nuovi seed di continente raggiungibili via porto).
2. **Ere continue e tecnologia senza fine**: dopo l'alta velocità arrivano maglev (2030), treni a vuoto (2070) e poi «generazioni» di veicoli ogni 15 anni con +8 % di prestazioni e obsolescenza dei precedenti; ricerca finanziabile con rendimenti decrescenti (+2 % efficienza per passo, costo ×1.5 a ogni passo). Rinnovare la flotta resta sempre necessario.
3. **Decadenza e rinnovo**: binari, ponti, gallerie e stazioni invecchiano e vanno rinnovati; giacimenti che si esauriscono e prospezione che ne scopre altri (mondo che si sposta); città che migrano verso il servizio migliore; cicli economici, crisi settoriali, stagioni che muovono l'agricoltura. Lo stato «ho comprato tutto» si erode da solo.
4. **Concorrenti rinnovabili e antitrust**: quando una compagnia supera il 60 % del mercato regionale nascono nuovi concorrenti finanziati dallo stato; sopra l'80 % scatta la legge antitrust: scorporo obbligatorio di una filiale (che diventa un concorrente) o multa annua crescente. Gli eventi regolatori cambiano con le ere (tariffe massime, obblighi di servizio, nazionalizzazione minacciata se la soddisfazione media scende sotto 0.3).
5. **Contratti e grandi opere generati** (`contracts.json`): lo stato e le città emettono bandi procedurali («collega X a Y entro 1890 con tempo < 2 h», «trasporta 50.000 t di grano prima del raccolto», «traforo delle Alpi: galleria di 12 km entro 8 anni») con premi, prestigio e penali; le grandi opere sono progetti pluriennali con cantieri dedicati. Esposizioni universali periodiche premiano record (linea più veloce, ponte più lungo, stazione più grande).
6. **Prestigio e dinastia**: punti prestigio da record, contratti, città fondate, primati tecnologici; Albo d'oro per seed. Modalità dinastia: ogni 30 anni la compagnia passa a un erede con un tratto (ingegnere: costi −10 %; finanziere: tasso −1 %; spendaccione: dividendi obbligatori) e una tassa di successione del 20 % del patrimonio: si riparte sempre con qualcosa da ricostruire.
7. **Modalità holding**: quando il giocatore controlla oltre l'80 % di una regione, la gestione operativa può essere delegata a un direttore (personale qualificato assunto, con competenza che cresce) al quale si danno obiettivi e budget; il giocatore passa a gestire più regioni, la borsa e i mercati mondiali (esportazioni contro compagnie estere astratte con prezzi propri). Il gioco cambia scala invece di finire.
8. **Nuova partita+**: prestigio convertibile in vantaggi permanenti (una tecnologia in anticipo, una concessione gratuita, un erede migliore) su una mappa nuova con difficoltà superiore; classifiche offline per seed e anno.
Ordine di implementazione consigliato: 3 → 5 → 4 → 1 → 2 → 6 → 7 → 8.
## 14. Protocollo, server, client, deploy, test
### 14.1 Protocollo (`src/ViaFerrea.Protocol`)
- Frame `[u32 length][u16 messageId][payload]`, little endian, massimo 4 MB. Handshake `Hello { protocolVersion, clientVersion, token }` → `Welcome { sessionId, worldSummary, dataHash, difficulty }` o `Reject`.
- Client → Server: Hello, Ping, Subscribe { viewport }, Command { seq, type, payload }, SetSpeed, ListSaves, Save, Load, NewGame { seed, size, startYear, difficultyPreset, overrides, endlessFlags }.
- Comandi: BuildTrack { polyline, heightOffset, allowBridges, allowTunnels, trackClass, doubleTrack, electrified }, RenewTrack, UpgradeTrack, Demolish, BuildStation, BuildDepot { size }, PlaceSignal, BuyVehicle, SellVehicle, ComposeTrain, CreateLine, EditLine, AssignTrain, SendToDepot, SetReserve, SetMaintenancePolicy { scope, level }, ScheduleService { trainId, kind }, OrderParts { depotId, qty }, TakeLoan, RepayLoan, AcceptAgreement, RejectAgreement, BuyGoods, SellGoods, BuyIndustry, SetIndustryPolicy, OverhaulIndustry, UpgradeIndustry, Ipo, BuyShares, SellShares, PayDividend, LaunchBid, RespondBid, BuyConcession, AcceptContract, FundResearch, DelegateRegion.
- Server → Client: Welcome, Reject, Pong, MapChunk, EntitySnapshot, EntityDelta, TrackWorks (opere per arco: tipo, altezze, stato cantiere), TrainMotion { trainId, segments[], state, condition }, DailyDigest { date, cash, netWorth, rating, prices[], events[], stateHash, slow }, MaintenanceAlert, EmploymentReport (mensile), MarketTape (giornaliero: prezzi azioni, offerte in corso), CommandResult, Notification, Newspaper (mensile: la «Cronaca»).
- Serializzazione a mano con `Write(ref SpanWriter)` / `Read(ref SpanReader)`; id stabili, nuovi campi in coda dopo un `byte flags`. Interest management: TrainMotion solo nel viewport (margine un chunk), massimo 10 aggiornamenti/s per treno.
### 14.2 Server (`src/ViaFerrea.Server`)
- Config da ambiente: `VF_PORT` (7400), `VF_TOKEN`, `VF_DATA_DIR` (/data), `VF_TICK_MS` (50), `VF_AUTOSAVE_MIN` (10), `VF_SEED`, `VF_MAP_SIZE`, `VF_DIFFICULTY`, `VF_LOG_LEVEL`; argomenti `--local` (porta 0 casuale, stampa `LISTENING <porta>`) e `--healthcheck` (GET su /health, exit 0/1).
- `GameLoop` su thread dedicato con accumulatore (Stopwatch); se un tick supera il budget riduce la velocità effettiva e segnala `slow`. Comandi da `ConcurrentQueue` drenata a inizio tick.
- `SessionManager`: WebSocket su `/ws`, token nell'Hello, coda di invio per sessione con backpressure, riconnessione con `sessionId`.
- HTTP: `GET /health`, `GET /api/saves`, `GET /api/saves/{id}`, `POST /api/saves`, `GET /metrics` (formato Prometheus: tick_ms, trains, packets, contracts, sessions). Autosave in `$VF_DATA_DIR/saves/` con rotazione degli ultimi 5. Log JSON su stdout.
### 14.3 Client Godot (`client/ViaFerrea.Client`)
- Scene: `Main` → `Menu`, `Connect` (immagine 09), `Game` = `MapView` (Node2D + Camera2D) + `Hud` (CanvasLayer) + `Panels/` (Market, Industry, Train, Maintenance, Fleet, Employment, Finance, Lines, Companies, Contracts, Regions, TrackProfile).
- `NetClient` con `ClientWebSocket`; `LocalServerLauncher` avvia `server/ViaFerrea.Server(.exe)` con `--local --token <guid>`, legge `LISTENING <porta>`, termina il processo alla chiusura.
- Rendering (immagini 01–04): `TerrainLayer` (ImageTexture per chunk: fasce altimetriche, hillshade verso sud-est, curve di livello ogni 20 m a zoom > 1, sponde); `TrackLayer` (massicciata #bfb79f, traversine #5b4a39 ogni 5,3 unità, rotaie #3b3f42 a ±2,4; rilevati come banda chiara con ombra, trincee come banda scura, ponti con pile ogni 30 m e spallette, gallerie con portali e binario tratteggiato; cantieri con tratteggio #8a7a52 e barriera ambra); `EntityLayer` (impronte dell'immagine 04, foreste con MultiMeshInstance2D, campi a strisce); `TrainLayer` (forme dell'immagine 03, interpolazione dei segmenti, fumo con GPUParticles2D, sfumatura di colore sui veicoli con condizione < 40 e icona di avviso); LOD a zoom < 0,4 e < 0,15.
- Strumento binari: tracciamento con snap a 45°, cursore di altezza, interruttori ponti/gallerie, classe; pannello `TrackProfile` con grafico altimetrico e riepilogo opere, costo, giorni; conferma → `BuildTrack`.
- UI: Theme con palette dell'immagine 05; font Big Shoulders Display e IBM Plex Sans (OFL in `assets/fonts/`); barra superiore, toolbar sinistra, pannello destro, ticker, minimappa (immagine 01); pannelli 06, 07, 08 a tutto schermo; tooltip «perché» su ogni valore.
### 14.4 Docker, Unraid, Gitea
```
FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
WORKDIR /src
COPY . .
RUN dotnet publish src/ViaFerrea.Server -c Release -o /app
FROM mcr.microsoft.com/dotnet/aspnet:10.0
WORKDIR /app
COPY --from=build /app .
RUN adduser --disabled-password --gecos "" vf && mkdir -p /data && chown vf /data
USER vf
ENV VF_PORT=7400 VF_DATA_DIR=/data ASPNETCORE_URLS=http://0.0.0.0:7400
EXPOSE 7400
VOLUME /data
HEALTHCHECK --interval=30s --timeout=5s CMD ["dotnet","ViaFerrea.Server.dll","--healthcheck"]
ENTRYPOINT ["dotnet","ViaFerrea.Server.dll"]
```
- `docker/docker-compose.yml`: servizio via-ferrea, porta 7400:7400, volume ./data:/data, env VF_TOKEN e VF_DIFFICULTY, restart unless-stopped.
- `docker/unraid-template.xml`: Repository `<registry Gitea>/via-ferrea-server:latest`, rete bridge, porta 7400, volume /mnt/user/appdata/via-ferrea → /data, variabili VF_TOKEN e VF_DIFFICULTY, WebUI http://[IP]:[PORT:7400]/health.
- `scripts/publish-image.sh`: build con tag versione (da Directory.Build.props) e latest, push sul registry Gitea. TLS a carico del reverse proxy o della rete privata (README).
### 14.5 Test e strumenti
- `tests/ViaFerrea.Tests`: harness interno (`[Test]` via reflection, `Assert` Equal/True/Throws/Approx, exit code); unico comando `dotnet run --project tests/ViaFerrea.Tests`.
- Test obbligatori: determinismo (stesso seed + stessi comandi, IA comprese → stesso hash dopo 5 anni); invarianti di merci e denaro; round-trip salvataggio e di ogni messaggio; validazione dati; profilo altimetrico (le due passate rispettano `gMax`, classificazione opere, costo, ponte obbligatorio sull'acqua, campata massima per era); usura e rischio monotoni nella condizione; tagliando e revisione riportano la condizione attesa; pianificatore predittivo non lascia scendere un treno sotto 30 con politica Standard e ricambi disponibili; pendolarismo (un'industria con città raggiungibile e capacità sufficiente raggiunge copertura > 0.9 in 60 giorni); IA (non emette comandi rifiutati più del 5 % delle volte; con capitale ×2 supera il giocatore passivo in 10 anni); borsa (scalata ostile completata quando il flottante lo consente); scenario di riferimento `tests/scenarios/valdoria.json`.
- `src/ViaFerrea.Tools`: `validate-data`, `genmap --seed --size --out mappa.bmp`, `profile --seed --polyline --out profilo.csv`, `simulate --seed --years --difficulty --scenario --out kpi.csv` (CSV con separatore `;`: anno; compagnia; bene; prezzo medio; produzione; consumo; popolazione; efficienza media; condizione media flotta; condizione media impianti; cassa; patrimonio; quota di mercato; nota), `bench --trains 2000`, `replay --save --commands`.
## 15. Obiettivi di prestazione (mappa 256 km, una regione)
- 2.000 treni, 600 stazioni, 400 industrie, 60 città, 5 IA: tick medio ≤ 10 ms su server a 4 core a 1×, 8× sostenibile; con 4 regioni ≤ 25 ms.
- Pianificatore di manutenzione e matcher del pendolarismo: ≤ 20 ms al giorno di gioco.
- Client a 60 fps in 1080p; banda in regime < 100 KB/s per client.
## 16. Roadmap: task e criteri di accettazione
**F0 Fondamenta**
1. Sezione 3, `Directory.Build.props`, `scripts/`, `CLAUDE.md`, `docs/` (GDD, ARCHITECTURE, PROTOCOL bozza, GUIDA, STATE, adr/0001-stack.md), harness di test con un test vero.
Accettazione: `scripts/build.sh` e `scripts/test.sh` verdi da cartella pulita; check-nuget passa.
**F1 Economia headless**
2. Clock, Rng, Money, id, DataLoader e validatore, tutti i file `data/` (≥ 12 beni compresi ricambi e macchinari, 14 industrie, 8 veicoli, 4 ere, 5 livelli, 4 difficoltà).
3. Generatore mappa (6.2) con giacimenti a riserva e `genmap`. Accettazione: mappa 128 km in < 3 s; distanze rispettate.
4. Industrie, città, hub, mercato, migrazione, difficoltà applicata; StateHasher; SaveFile. Accettazione: `simulate --years 20` in < 60 s; prezzi entro i limiti; nessun bene dal nulla; determinismo e round-trip verdi.
**F2 Rete ferroviaria realistica headless**
5. `TerrainSampler`, `TrackPlanner` (profilo, opere, costi, tempi, vincoli per era), `Crew` e cantieri, classi di binario, usura del binario, ponti e gallerie con condizione; `profile` nei Tools.
6. TrackGraph, stazioni, depositi, segnali, A*, treni con fisica e `Stalled`, linee e ordini.
7. LineGraph, pacchetti, tariffe, costi.
Accettazione: scenario `valdoria.json` con una collina e un fiume tra miniera e acciaieria: il tracciato diretto viola `gMax` e viene rifiutato; il tracciato con trincea + ponte è accettato, costa più del doppio e si completa in tempi coerenti; con tre linee (merci, lavoratori, personale) l'acciaieria passa da < 40 % a > 80 % in 2 anni senza deadlock; `bench --trains 2000` ≤ 10 ms.
**F3 Server e client minimo**
8. Protocol completo con round-trip; Server (14.2); Docker (14.4).
9. Client: Connect, MapView con terreno, curve di livello, opere, entità, treni; strumento binari con `TrackProfile`; stazioni, depositi, treni, linee; HUD; velocità.
Accettazione: dalla partita locale e dal server Docker si costruisce una linea con un ponte, si compra un treno e lo si vede muovere con posizione coerente al server (scarto < 1 cella); l'anteprima del profilo coincide con il risultato del server.
**F4 Pendolarismo e manutenzione dei treni**
10. Sezione 9 completa con Registro degli impieghi e convenzioni.
11. Sezione 10 completa: componenti, guasti, soccorso, interventi, ricambi via treno, personale dei depositi, politiche, pianificatore, riserve, cartelle e registri.
Accettazione: test di 14.5 su pendolarismo e manutenzione; nello scenario, senza linea dei ricambi la flotta scende sotto condizione 40 entro 3 anni e i guasti raddoppiano; con la linea resta sopra 60.
**F5 Industrie, IA, borsa, scalate**
12. Sezione 11 (manutenzione industrie, fermi, ammodernamenti, acquisto industrie con pannello del proprietario).
13. Sezione 12 (agenti IA, personalità, borsa, quotazione, scalate, esiti per difficoltà, Cronaca finale, osservatore).
Accettazione: test IA e borsa di 14.5; determinismo con IA; su «Magnate» almeno un'IA raggiunge il livello 3 in 15 anni con giocatore passivo.
**F6 Economia completa, eventi, rifinitura**
14. Hub, eventi, storico prezzi, finanza completa, livelli e sblocchi, ere e obsolescenza; pannelli 06–08 definitivi; tooltip «perché»; tutorial; audio; bilanciamento con bot su `simulate`; export Windows con server in `server/`.
**F7 Gioco infinito**
15. Sezione 13 nell'ordine 3 → 5 → 4 → 1 → 2 → 6 → 7 → 8, ciascuno con test di determinismo e salvataggio compatibile (migrazioni).
Accettazione: partita di 200 anni simulata con bot che non entra mai in stato «nulla da fare»: ogni anno esiste almeno un contratto aperto, un'opera da rinnovare o una regione acquistabile.
## 17. Immagini di riferimento (`reference/`)
- 01_vista_mappa: layout della schermata di gioco. 02_paesaggio_binari_zoom: binari, opere, stazioni, industrie, treni a zoom ravvicinato. 03_treni_dall_alto: locomotive per era e carri, proporzioni (larghezza 9, carro 16, carrozza 20, loco 20–26 unità). 04_edifici_industrie_paesaggio: impronte dall'alto. 05_palette_tipografia_ui: colori, font, componenti. 06–09: pannelli a tutto schermo.
- Regola: vista sempre dall'alto, nessuna prospettiva; leggibilità della simulazione prima dell'effetto scenico. Le opere (rilevati, trincee, ponti, gallerie) si disegnano con le stesse primitive e la stessa palette.
## 18. Chiusura di ogni sessione
- Esegui `scripts/build.sh` e `scripts/test.sh`; aggiorna `docs/STATE.md` (fatto, in corso, prossimo passo, versioni degli strumenti, misure di prestazione reali); commit `F<n>: <cosa>`.
- Riepilogo in chat: cosa è stato fatto, decisioni con ADR, limiti noti, prossimo comando da darti.
+96
View File
@@ -0,0 +1,96 @@
# Via Ferrea — Protocollo di rete (bozza)
Stato: **bozza F0**. Diventa normativo in F3, quando ogni messaggio avrà il test di round-trip.
## 1. Trasporto
- WebSocket su `ws://<host>:<porta>/ws` (TLS a carico del reverse proxy: `wss://`).
- Solo messaggi binari. Un messaggio WebSocket contiene esattamente un frame.
- Porta predefinita 7400 (`VF_PORT`).
## 2. Frame
```
offset tipo campo
0 u32 length lunghezza di messageId + payload (byte)
4 u16 messageId identificativo stabile del messaggio
6 ... payload corpo serializzato a mano
```
- Little endian. Dimensione massima 4 MB (`length ≤ 4 194 298`): frame più grandi chiudono la connessione con codice 1009.
- Serializzazione con `SpanWriter`/`SpanReader` (`Write(ref SpanWriter)` / `Read(ref SpanReader)` per ogni messaggio). Nessuna reflection, nessun JSON.
### Tipi elementari
| Tipo | Codifica |
|---|---|
| `bool` | 1 byte, 0 o 1 |
| `u8/u16/u32/u64`, `i8…i64` | little endian a larghezza fissa |
| `varuint` | LEB128 (lunghezze e conteggi) |
| `f32/f64` | IEEE 754 little endian |
| `string` | `varuint` lunghezza in byte + UTF-8 |
| `Money` | `i64` centesimi |
| identità (`StationId`…) | `i32` |
| liste | `varuint` conteggio + elementi |
### Evoluzione
- Gli id dei messaggi e l'ordine dei campi non cambiano mai.
- I campi nuovi si aggiungono in coda, dopo un `u8 flags` che dice quali blocchi opzionali seguono. Un lettore vecchio ignora i byte residui del payload.
- `protocolVersion` cresce solo per modifiche incompatibili.
## 3. Handshake
```
Client → Hello { protocolVersion: u16, clientVersion: string, token: string, resumeSessionId: u64 (0 = nuova) }
Server → Welcome { sessionId: u64, worldSummary, dataHash: u64, difficulty: string }
| Reject { code: u16, reason: string }
```
Codici di `Reject`: 1 versione del protocollo, 2 token errato, 3 dati diversi, 4 server pieno, 5 partita non caricata.
## 4. Messaggi Client → Server
| id | Nome | Contenuto |
|---|---|---|
| 1 | Hello | vedi handshake |
| 2 | Ping | `nonce: u64` |
| 3 | Subscribe | `viewport` (rettangolo in celle), livello di dettaglio |
| 4 | Command | `seq: u32`, `type: u16`, `payload` del comando |
| 5 | SetSpeed | `speed: u8` (0, 1, 2, 4, 8) |
| 6 | ListSaves | — |
| 7 | Save | `name: string` |
| 8 | Load | `id: string` |
| 9 | NewGame | `seed`, `size`, `startYear`, `difficultyPreset`, `overrides`, `endlessFlags` |
### Comandi (`Command.type`)
BuildTrack, RenewTrack, UpgradeTrack, Demolish, BuildStation, BuildDepot, PlaceSignal, BuyVehicle, SellVehicle, ComposeTrain, CreateLine, EditLine, AssignTrain, SendToDepot, SetReserve, SetMaintenancePolicy, ScheduleService, OrderParts, TakeLoan, RepayLoan, AcceptAgreement, RejectAgreement, BuyGoods, SellGoods, BuyIndustry, SetIndustryPolicy, OverhaulIndustry, UpgradeIndustry, Ipo, BuyShares, SellShares, PayDividend, LaunchBid, RespondBid, BuyConcession, AcceptContract, FundResearch, DelegateRegion.
I codici numerici dei comandi coincidono con l'enum `CommandType` di Core e non cambiano mai.
## 5. Messaggi Server → Client
| id | Nome | Contenuto |
|---|---|---|
| 101 | Welcome | vedi handshake |
| 102 | Reject | vedi handshake |
| 103 | Pong | `nonce: u64`, `serverTick: u64` |
| 110 | MapChunk | coordinate del chunk 64×64, altezze, tipi cella |
| 111 | EntitySnapshot | stato completo delle entità visibili |
| 112 | EntityDelta | variazioni dall'ultimo snapshot |
| 113 | TrackWorks | opere per arco: tipo, altezze, stato del cantiere |
| 114 | TrainMotion | `trainId`, segmenti di moto, stato, condizione |
| 120 | DailyDigest | data, cassa, patrimonio, rating, prezzi, eventi, `stateHash`, `slow` |
| 121 | MaintenanceAlert | treno o deposito, componente, scadenza |
| 122 | EmploymentReport | mensile |
| 123 | MarketTape | giornaliero: prezzi delle azioni, offerte in corso |
| 130 | CommandResult | `seq`, esito, codice di errore, messaggio |
| 131 | Notification | livello, testo, riferimento all'entità |
| 132 | Newspaper | mensile: la «Cronaca» |
## 6. Interest management
- `TrainMotion` solo per i treni nel viewport sottoscritto più un chunk di margine, al massimo 10 aggiornamenti al secondo per treno.
- I chunk della mappa si inviano su richiesta implicita (viewport) e una sola volta per sessione, salvo modifiche.
- Obiettivo di banda in regime: < 100 KB/s per client.
+44
View File
@@ -0,0 +1,44 @@
# Via Ferrea — Stato dei lavori
Aggiornato alla fine di ogni fase (guida, sezione 18).
## Versioni degli strumenti
| Strumento | Versione | Note |
|---|---|---|
| .NET SDK | 10.0.112 | da apt (Ubuntu 24.04, `dotnet-sdk-10.0`) |
| Runtime .NET / ASP.NET Core | 10.0.12 | |
| Targeting pack net8.0 | 8.0.31 | `dotnet-targeting-pack-8.0`, per Core e Protocol |
| Godot .NET | non installato | github.com non raggiungibile dall'ambiente cloud; `Godot.NET.Sdk` 4.7.2 è su NuGet |
| Docker CLI | 29.6.2 | demone non attivo nell'ambiente cloud |
| Sistema | Ubuntu 24.04.4 LTS x86_64, 4 core, 15 GB | |
## Fatto
### F0 — Fondamenta
- Soluzione `ViaFerrea.sln` con Core, Protocol (net10.0 + net8.0), Server (Web SDK), Tools (`viaferrea-tools`), Tests.
- `Directory.Build.props` con Nullable, ImplicitUsings, LangVersion latest, warning come errori, globalizzazione invariante, build deterministica, versione unica (0.1.0).
- Script: `build.sh`, `build.ps1`, `test.sh`, `check-nuget.sh`, `publish-image.sh`.
- Documenti: GUIDA (copia della specifica v2), GDD, ARCHITECTURE, PROTOCOL (bozza), STATE, ADR 0001 (stack).
- Harness di test interno (`[Test]`, `Assert`, esecuzione parallela, filtri, `--skip-slow`) con i primi test reali su `Rng` (vettore di riferimento di xoshiro256**).
- Immagini di riferimento 01–05 in `reference/`.
## In corso
- F1 — Economia headless.
## Prossimo passo
- F1.2: Clock, Money, identità tipizzate, DataLoader con source generator, validatore di schema e semantico, file `data/*.json` completi.
## Limiti noti
- Le immagini di riferimento 06–09 (pannelli a tutto schermo e schermata di connessione) non sono state fornite: i pannelli seguiranno palette e componenti dell'immagine 05 finché non arrivano.
- Godot non è eseguibile nell'ambiente cloud: il client potrà essere compilato con `Godot.NET.Sdk` ma non avviato né esportato qui.
## Misure di prestazione
| Misura | Valore | Fase |
|---|---|---|
| Build Release da pulito | ~15 s | F0 |
| Test (5) | < 0,1 s | F0 |
+23
View File
@@ -0,0 +1,23 @@
# ADR 0001 — Stack tecnologico
Stato: accettato (F0).
## Contesto
La guida (sezioni 1 e 3) fissa C# 14 su .NET 10, ASP.NET Core come shared framework per il server, Godot 4 .NET per il client e il divieto di pacchetti NuGet. In fase di avvio vanno fissati alcuni dettagli che la guida lascia aperti.
## Decisione
1. **SDK**: .NET SDK 10.0.1xx. Nell'ambiente di sviluppo cloud è installato dai repository Ubuntu 24.04 (`dotnet-sdk-10.0`, più `dotnet-targeting-pack-8.0` per compilare Core e Protocol anche per net8.0 senza scaricare pacchetti di riferimento).
2. **Formato della soluzione**: `ViaFerrea.sln` classico (non `.slnx`, che .NET 10 crea per default) per compatibilità con Godot e con gli strumenti più vecchi; si crea con `dotnet new sln -n ViaFerrea --format sln`.
3. **Target**: Core e Protocol `net10.0;net8.0` perché il client Godot 4.x compila per net8.0; Server, Tools e Tests solo `net10.0`. In Core e Protocol non si usano API successive a .NET 8.
4. **Godot**: versione stabile più recente pubblicata, 4.7.2. Il client usa `Godot.NET.Sdk/4.7.2`; è l'unica dipendenza esterna ammessa e sta fuori dalla soluzione principale, quindi `check-nuget.sh` esclude `client/`.
5. **Punti d'ingresso espliciti**: i progetti eseguibili usano classi `static Main` con nome proprio (`ServerProgram`, `ToolsProgram`, `TestProgram`) invece delle istruzioni di primo livello, perché il progetto di test referenzia il server e due tipi `Program` globali entrerebbero in conflitto (CS0436 trattato come errore).
6. **Harness di test**: interno, in `tests/ViaFerrea.Tests/Harness`, con esecuzione parallela dei test indipendenti; i test marcati `Isolated` girano da soli, quelli `Slow` si possono escludere con `--skip-slow`.
7. **Strumenti**: l'eseguibile dei Tools si chiama `viaferrea-tools` (`AssemblyName`), come nei comandi della guida.
## Conseguenze
- Build e test non richiedono rete dopo l'installazione dell'SDK: nessun restore da feed esterni.
- Se Godot passa a net9.0 o net10.0 basta allineare il TargetFramework del client; Core e Protocol restano compatibili verso il basso.
- Il divieto di API post-.NET 8 in Core va ricordato nelle revisioni (il build net8.0 lo fa rispettare in automatico).
Binary file not shown.

After

Width:  |  Height:  |  Size: 264 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 220 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 209 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 191 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 184 KiB

+34
View File
@@ -0,0 +1,34 @@
# Compila la soluzione su Windows (equivalente di scripts/build.sh).
# Uso: ./scripts/build.ps1 [-Configuration Release] [-Client]
param(
[string]$Configuration = "Release",
[switch]$Client,
[switch]$Test
)
$ErrorActionPreference = "Stop"
Set-Location (Join-Path $PSScriptRoot "..")
$env:DOTNET_CLI_TELEMETRY_OPTOUT = "1"
$env:DOTNET_NOLOGO = "1"
# Regola: zero pacchetti NuGet fuori dal client Godot.
$bad = Get-ChildItem -Recurse -Include *.csproj,*.props,*.targets |
Where-Object { $_.FullName -notmatch '[\\/](client|bin|obj|\.git)[\\/]' } |
Where-Object { Select-String -Path $_.FullName -Pattern '<PackageReference|<PackageVersion|<GlobalPackageReference' -Quiet }
if ($bad) { $bad | ForEach-Object { Write-Error "Pacchetto NuGet in $($_.FullName)" }; exit 1 }
dotnet build ViaFerrea.sln -c $Configuration -nologo -v minimal
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
if ($Test) {
dotnet run --project tests/ViaFerrea.Tests -c $Configuration --no-build
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
}
if ($Client) {
# Il server locale viene pubblicato dentro la cartella del client esportato.
dotnet publish src/ViaFerrea.Server -c $Configuration -r win-x64 --self-contained true -o client/ViaFerrea.Client/export/windows/server
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
dotnet build client/ViaFerrea.Client/ViaFerrea.Client.csproj -c $Configuration
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
}
Write-Host "build: ok ($Configuration)"
+11
View File
@@ -0,0 +1,11 @@
#!/usr/bin/env bash
# Compila l'intera soluzione (Release per default) dopo il controllo dei pacchetti.
# Uso: scripts/build.sh [Debug|Release]
set -euo pipefail
cd "$(dirname "$0")/.."
config="${1:-Release}"
export DOTNET_CLI_TELEMETRY_OPTOUT=1 DOTNET_NOLOGO=1
scripts/check-nuget.sh
dotnet build ViaFerrea.sln -c "$config" -nologo -v minimal
echo "build: ok ($config)"
+25
View File
@@ -0,0 +1,25 @@
#!/usr/bin/env bash
# Fallisce se un progetto .NET della soluzione contiene un PackageReference (regola: zero NuGet).
# Il client Godot è escluso: il suo SDK è l'unica dipendenza esterna ammessa.
set -euo pipefail
cd "$(dirname "$0")/.."
found=0
while IFS= read -r -d '' f; do
if grep -qiE '<PackageReference|<PackageVersion|<GlobalPackageReference' "$f"; then
echo "ERRORE: riferimento a pacchetto NuGet in $f" >&2
grep -niE '<PackageReference|<PackageVersion|<GlobalPackageReference' "$f" >&2
found=1
fi
done < <(find . \( -path ./client -o -path ./.git -o -name bin -o -name obj \) -prune -o \
\( -name '*.csproj' -o -name '*.props' -o -name '*.targets' \) -print0)
if [ -f packages.config ] || [ -f Directory.Packages.props ]; then
echo "ERRORE: gestione centralizzata dei pacchetti non ammessa" >&2
found=1
fi
if [ "$found" -ne 0 ]; then
exit 1
fi
echo "check-nuget: nessun pacchetto NuGet"
+28
View File
@@ -0,0 +1,28 @@
#!/usr/bin/env bash
# Costruisce l'immagine Docker del server con il tag della versione (da Directory.Build.props)
# e "latest", poi la pubblica sul registry Gitea.
# Uso: VF_REGISTRY=gitea.lan:3000/utente scripts/publish-image.sh [--no-push]
set -euo pipefail
cd "$(dirname "$0")/.."
version="$(sed -n 's:.*<Version>\(.*\)</Version>.*:\1:p' Directory.Build.props | head -n1)"
if [ -z "$version" ]; then
echo "ERRORE: versione non trovata in Directory.Build.props" >&2
exit 1
fi
registry="${VF_REGISTRY:-}"
name="via-ferrea-server"
image="${registry:+$registry/}$name"
docker build -f docker/Dockerfile -t "$image:$version" -t "$image:latest" .
echo "immagine: $image:$version"
if [ "${1:-}" = "--no-push" ]; then
exit 0
fi
if [ -z "$registry" ]; then
echo "VF_REGISTRY non impostato: immagine solo locale (usa --no-push per non vedere questo avviso)" >&2
exit 0
fi
docker push "$image:$version"
docker push "$image:latest"
+13
View File
@@ -0,0 +1,13 @@
#!/usr/bin/env bash
# Esegue la validazione dei dati e tutti i test con l'harness interno.
# Uso: scripts/test.sh [filtri...] [--skip-slow] [--serial]
set -euo pipefail
cd "$(dirname "$0")/.."
export DOTNET_CLI_TELEMETRY_OPTOUT=1 DOTNET_NOLOGO=1
scripts/check-nuget.sh
dotnet build ViaFerrea.sln -c Release -nologo -v quiet
if [ -f src/ViaFerrea.Tools/Commands/ValidateDataCommand.cs ]; then
dotnet run --project src/ViaFerrea.Tools -c Release --no-build -- validate-data --data data
fi
dotnet run --project tests/ViaFerrea.Tests -c Release --no-build -- "$@"
+130
View File
@@ -0,0 +1,130 @@
namespace ViaFerrea.Core.Common;
/// <summary>
/// Generatore pseudo-casuale xoshiro256** (Blackman e Vigna), unico ammesso nella simulazione.
/// Lo stato è di 256 bit, serializzabile e indipendente dalla piattaforma.
/// Ogni sottosistema usa il proprio flusso ottenuto con <see cref="Fork"/>, così l'ordine
/// delle estrazioni di un sistema non perturba gli altri.
/// </summary>
public sealed class Rng
{
private ulong _s0, _s1, _s2, _s3;
/// <summary>Crea un generatore dal seme con l'espansione SplitMix64 raccomandata dagli autori.</summary>
public Rng(ulong seed)
{
ulong x = seed;
_s0 = SplitMix64(ref x);
_s1 = SplitMix64(ref x);
_s2 = SplitMix64(ref x);
_s3 = SplitMix64(ref x);
if ((_s0 | _s1 | _s2 | _s3) == 0) _s0 = 1; // lo stato tutto a zero è l'unico vietato
}
private Rng(ulong s0, ulong s1, ulong s2, ulong s3)
{
_s0 = s0; _s1 = s1; _s2 = s2; _s3 = s3;
if ((_s0 | _s1 | _s2 | _s3) == 0) _s0 = 1;
}
/// <summary>Crea un generatore con lo stato esatto (test e ripristino da salvataggio).</summary>
public static Rng FromState(ulong s0, ulong s1, ulong s2, ulong s3) => new(s0, s1, s2, s3);
/// <summary>Stato corrente, per salvataggi e hash.</summary>
public (ulong S0, ulong S1, ulong S2, ulong S3) State => (_s0, _s1, _s2, _s3);
/// <summary>
/// Deriva un flusso indipendente e stabile identificato da un nome. Non consuma numeri
/// da questo generatore: lo stesso nome sullo stesso stato dà sempre lo stesso flusso.
/// </summary>
public Rng Fork(string name)
{
ulong h = StableHash.Fnv1a64(name);
ulong x = _s0 ^ RotateLeft(_s1, 17) ^ RotateLeft(_s2, 31) ^ RotateLeft(_s3, 47) ^ h;
ulong a = SplitMix64(ref x), b = SplitMix64(ref x), c = SplitMix64(ref x), d = SplitMix64(ref x);
return new Rng(a, b, c, d);
}
/// <summary>Deriva un flusso indipendente da un nome e da un indice (per entità numerate).</summary>
public Rng Fork(string name, long index)
{
ulong h = StableHash.Fnv1a64(name) ^ (ulong)index * 0x9E3779B97F4A7C15UL;
ulong x = _s0 ^ RotateLeft(_s1, 17) ^ RotateLeft(_s2, 31) ^ RotateLeft(_s3, 47) ^ h;
ulong a = SplitMix64(ref x), b = SplitMix64(ref x), c = SplitMix64(ref x), d = SplitMix64(ref x);
return new Rng(a, b, c, d);
}
/// <summary>Prossimo intero a 64 bit.</summary>
public ulong NextU64()
{
ulong result = RotateLeft(_s1 * 5, 7) * 9;
ulong t = _s1 << 17;
_s2 ^= _s0;
_s3 ^= _s1;
_s1 ^= _s2;
_s0 ^= _s3;
_s2 ^= t;
_s3 = RotateLeft(_s3, 45);
return result;
}
/// <summary>Prossimo intero a 32 bit (bit alti, i migliori).</summary>
public uint NextU32() => (uint)(NextU64() >> 32);
/// <summary>Intero uniforme in [0, maxExclusive) senza distorsione (metodo di Lemire).</summary>
public int NextInt(int maxExclusive)
{
if (maxExclusive <= 0) throw new ArgumentOutOfRangeException(nameof(maxExclusive));
ulong range = (ulong)maxExclusive;
ulong x = NextU64() >> 32;
ulong m = x * range;
ulong low = m & 0xFFFFFFFFUL;
if (low < range)
{
ulong threshold = (0x1_0000_0000UL - range) % range;
while (low < threshold)
{
x = NextU64() >> 32;
m = x * range;
low = m & 0xFFFFFFFFUL;
}
}
return (int)(m >> 32);
}
/// <summary>Intero uniforme in [minInclusive, maxExclusive).</summary>
public int NextInt(int minInclusive, int maxExclusive)
{
if (maxExclusive <= minInclusive) throw new ArgumentOutOfRangeException(nameof(maxExclusive));
return minInclusive + NextInt(maxExclusive - minInclusive);
}
/// <summary>Reale uniforme in [0, 1) con 53 bit di mantissa.</summary>
public double NextDouble() => (NextU64() >> 11) * (1.0 / (1UL << 53));
/// <summary>Reale uniforme in [min, max).</summary>
public double NextDouble(double min, double max) => min + (max - min) * NextDouble();
/// <summary>Vero con probabilità p.</summary>
public bool Chance(double p) => p > 0 && (p >= 1 || NextDouble() < p);
/// <summary>Mescola un intervallo con Fisher-Yates.</summary>
public void Shuffle<T>(Span<T> items)
{
for (int i = items.Length - 1; i > 0; i--)
{
int j = NextInt(i + 1);
(items[i], items[j]) = (items[j], items[i]);
}
}
private static ulong RotateLeft(ulong x, int k) => (x << k) | (x >> (64 - k));
private static ulong SplitMix64(ref ulong x)
{
ulong z = x += 0x9E3779B97F4A7C15UL;
z = (z ^ (z >> 30)) * 0xBF58476D1CE4E5B9UL;
z = (z ^ (z >> 27)) * 0x94D049BB133111EBUL;
return z ^ (z >> 31);
}
}
+42
View File
@@ -0,0 +1,42 @@
using System.Text;
namespace ViaFerrea.Core.Common;
/// <summary>
/// Hash stabili tra processi e piattaforme (string.GetHashCode è randomizzato per processo e
/// non va mai usato per effetti di simulazione).
/// </summary>
public static class StableHash
{
private const ulong FnvOffset = 0xCBF29CE484222325UL;
private const ulong FnvPrime = 0x100000001B3UL;
/// <summary>FNV-1a a 64 bit sui byte UTF-8 della stringa.</summary>
public static ulong Fnv1a64(string text)
{
ulong h = FnvOffset;
Span<byte> buffer = stackalloc byte[256];
int max = Encoding.UTF8.GetMaxByteCount(text.Length);
byte[]? rented = max > buffer.Length ? new byte[max] : null;
Span<byte> bytes = rented ?? buffer;
int n = Encoding.UTF8.GetBytes(text, bytes);
for (int i = 0; i < n; i++)
{
h ^= bytes[i];
h *= FnvPrime;
}
return h;
}
/// <summary>FNV-1a a 64 bit su un intervallo di byte.</summary>
public static ulong Fnv1a64(ReadOnlySpan<byte> bytes, ulong seed = FnvOffset)
{
ulong h = seed;
for (int i = 0; i < bytes.Length; i++)
{
h ^= bytes[i];
h *= FnvPrime;
}
return h;
}
}
+10
View File
@@ -0,0 +1,10 @@
<Project Sdk="Microsoft.NET.Sdk">
<!-- Motore di simulazione deterministico: nessuna dipendenza oltre la BCL. -->
<PropertyGroup>
<TargetFrameworks>net10.0;net8.0</TargetFrameworks>
<RootNamespace>ViaFerrea.Core</RootNamespace>
<IsTrimmable>true</IsTrimmable>
</PropertyGroup>
</Project>
@@ -0,0 +1,14 @@
<Project Sdk="Microsoft.NET.Sdk">
<!-- Frame binari del protocollo WebSocket, condivisi da server e client. -->
<PropertyGroup>
<TargetFrameworks>net10.0;net8.0</TargetFrameworks>
<RootNamespace>ViaFerrea.Protocol</RootNamespace>
<IsTrimmable>true</IsTrimmable>
</PropertyGroup>
<ItemGroup>
<ProjectReference Include="..\ViaFerrea.Core\ViaFerrea.Core.csproj" />
</ItemGroup>
</Project>
+17
View File
@@ -0,0 +1,17 @@
namespace ViaFerrea.Server;
/// <summary>
/// Punto d'ingresso del server autorevole. In F0 espone solo /health; il ciclo di gioco,
/// le sessioni WebSocket e le API dei salvataggi arrivano in F3.
/// </summary>
public static class ServerProgram
{
public static int Main(string[] args)
{
var builder = WebApplication.CreateSlimBuilder(args);
var app = builder.Build();
app.MapGet("/health", () => Results.Text("ok"));
app.Run();
return 0;
}
}
@@ -0,0 +1,19 @@
<Project Sdk="Microsoft.NET.Sdk.Web">
<!-- Server autorevole: ASP.NET Core usato solo come shared framework. -->
<PropertyGroup>
<TargetFramework>net10.0</TargetFramework>
<RootNamespace>ViaFerrea.Server</RootNamespace>
</PropertyGroup>
<ItemGroup>
<ProjectReference Include="..\ViaFerrea.Core\ViaFerrea.Core.csproj" />
<ProjectReference Include="..\ViaFerrea.Protocol\ViaFerrea.Protocol.csproj" />
</ItemGroup>
<!-- I file dati viaggiano accanto all'eseguibile. -->
<ItemGroup>
<Content Include="..\..\data\**\*.json" LinkBase="data" CopyToOutputDirectory="PreserveNewest" CopyToPublishDirectory="PreserveNewest" />
</ItemGroup>
</Project>
+9
View File
@@ -0,0 +1,9 @@
{
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft.AspNetCore": "Warning"
}
},
"AllowedHosts": "*"
}
+23
View File
@@ -0,0 +1,23 @@
namespace ViaFerrea.Tools;
/// <summary>Strumenti da riga di comando di Via Ferrea.</summary>
public static class ToolsProgram
{
public static int Main(string[] args)
{
if (args.Length == 0 || args[0] is "-h" or "--help" or "help")
{
PrintHelp();
return args.Length == 0 ? 1 : 0;
}
Console.Error.WriteLine($"Comando sconosciuto: {args[0]}");
PrintHelp();
return 1;
}
private static void PrintHelp()
{
Console.WriteLine("viaferrea-tools <comando> [opzioni]");
Console.WriteLine(" (i comandi arrivano dalla Fase 1)");
}
}
@@ -0,0 +1,20 @@
<Project Sdk="Microsoft.NET.Sdk">
<!-- Strumenti da riga di comando: validate-data, genmap, profile, simulate, bench, replay. -->
<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>net10.0</TargetFramework>
<AssemblyName>viaferrea-tools</AssemblyName>
<RootNamespace>ViaFerrea.Tools</RootNamespace>
</PropertyGroup>
<ItemGroup>
<ProjectReference Include="..\ViaFerrea.Core\ViaFerrea.Core.csproj" />
<ProjectReference Include="..\ViaFerrea.Protocol\ViaFerrea.Protocol.csproj" />
</ItemGroup>
<ItemGroup>
<Content Include="..\..\data\**\*.json" LinkBase="data" CopyToOutputDirectory="PreserveNewest" />
</ItemGroup>
</Project>
+66
View File
@@ -0,0 +1,66 @@
using ViaFerrea.Core.Common;
using ViaFerrea.Tests.Harness;
namespace ViaFerrea.Tests.Core;
public static class RngTests
{
[Test(Description = "Vettore di riferimento di xoshiro256** con stato {1,2,3,4}")]
public static void Xoshiro256StarStarMatchesReferenceVector()
{
var rng = Rng.FromState(1, 2, 3, 4);
Assert.Equal(11520UL, rng.NextU64());
Assert.Equal(0UL, rng.NextU64());
Assert.Equal(1509978240UL, rng.NextU64());
Assert.Equal(1215971899390074240UL, rng.NextU64());
}
[Test]
public static void SameSeedGivesSameSequence()
{
var a = new Rng(42);
var b = new Rng(42);
for (int i = 0; i < 1000; i++) Assert.Equal(a.NextU64(), b.NextU64());
}
[Test]
public static void ForkIsStableAndDoesNotConsumeParent()
{
var root = new Rng(7);
var before = root.State;
var f1 = root.Fork("industries");
var f2 = root.Fork("industries");
var f3 = root.Fork("towns");
Assert.Equal(before, root.State);
Assert.Equal(f1.NextU64(), f2.NextU64());
Assert.NotEqual(new Rng(7).Fork("industries").NextU64(), f3.NextU64());
}
[Test]
public static void NextIntIsInRangeAndRoughlyUniform()
{
var rng = new Rng(123);
var counts = new int[10];
for (int i = 0; i < 100_000; i++)
{
int v = rng.NextInt(10);
Assert.True(v is >= 0 and < 10);
counts[v]++;
}
foreach (int c in counts) Assert.InRange(c, 9_500, 10_500);
}
[Test]
public static void NextDoubleIsInUnitInterval()
{
var rng = new Rng(99);
double sum = 0;
for (int i = 0; i < 100_000; i++)
{
double d = rng.NextDouble();
Assert.True(d >= 0 && d < 1);
sum += d;
}
Assert.Approx(0.5, sum / 100_000, 0.01);
}
}
+99
View File
@@ -0,0 +1,99 @@
using System.Runtime.CompilerServices;
namespace ViaFerrea.Tests.Harness;
/// <summary>Fallimento di un'asserzione, con posizione nel sorgente.</summary>
public sealed class AssertionException(string message) : Exception(message);
/// <summary>Asserzioni minime del harness interno.</summary>
public static class Assert
{
public static void Equal<T>(T expected, T actual, string? message = null,
[CallerFilePath] string file = "", [CallerLineNumber] int line = 0)
{
if (!EqualityComparer<T>.Default.Equals(expected, actual))
Fail($"atteso <{expected}> ma ottenuto <{actual}>", message, file, line);
}
public static void NotEqual<T>(T notExpected, T actual, string? message = null,
[CallerFilePath] string file = "", [CallerLineNumber] int line = 0)
{
if (EqualityComparer<T>.Default.Equals(notExpected, actual))
Fail($"valore diverso da <{notExpected}> atteso", message, file, line);
}
public static void SequenceEqual<T>(IEnumerable<T> expected, IEnumerable<T> actual, string? message = null,
[CallerFilePath] string file = "", [CallerLineNumber] int line = 0)
{
var e = expected.ToList();
var a = actual.ToList();
if (e.Count != a.Count)
Fail($"lunghezze diverse: attese {e.Count}, ottenute {a.Count}", message, file, line);
for (int i = 0; i < e.Count; i++)
{
if (!EqualityComparer<T>.Default.Equals(e[i], a[i]))
Fail($"elemento {i}: atteso <{e[i]}> ma ottenuto <{a[i]}>", message, file, line);
}
}
public static void True(bool condition, string? message = null,
[CallerFilePath] string file = "", [CallerLineNumber] int line = 0)
{
if (!condition) Fail("condizione falsa", message, file, line);
}
public static void False(bool condition, string? message = null,
[CallerFilePath] string file = "", [CallerLineNumber] int line = 0)
{
if (condition) Fail("condizione vera", message, file, line);
}
public static void NotNull(object? value, string? message = null,
[CallerFilePath] string file = "", [CallerLineNumber] int line = 0)
{
if (value is null) Fail("valore nullo", message, file, line);
}
/// <summary>Confronto tra reali con tolleranza assoluta.</summary>
public static void Approx(double expected, double actual, double tolerance, string? message = null,
[CallerFilePath] string file = "", [CallerLineNumber] int line = 0)
{
if (double.IsNaN(actual) || Math.Abs(expected - actual) > tolerance)
Fail($"atteso {expected} ± {tolerance} ma ottenuto {actual}", message, file, line);
}
/// <summary>Verifica che value sia nell'intervallo chiuso [min, max].</summary>
public static void InRange(double value, double min, double max, string? message = null,
[CallerFilePath] string file = "", [CallerLineNumber] int line = 0)
{
if (double.IsNaN(value) || value < min || value > max)
Fail($"valore {value} fuori da [{min}, {max}]", message, file, line);
}
public static TException Throws<TException>(Action action, string? message = null,
[CallerFilePath] string file = "", [CallerLineNumber] int line = 0) where TException : Exception
{
try
{
action();
}
catch (TException ex)
{
return ex;
}
catch (Exception ex)
{
Fail($"attesa {typeof(TException).Name} ma lanciata {ex.GetType().Name}: {ex.Message}", message, file, line);
}
Fail($"attesa {typeof(TException).Name} ma nessuna eccezione", message, file, line);
return null!;
}
[System.Diagnostics.CodeAnalysis.DoesNotReturn]
public static void Fail(string reason, string? message = null,
[CallerFilePath] string file = "", [CallerLineNumber] int line = 0)
{
string where = $"{Path.GetFileName(file)}:{line}";
throw new AssertionException(message is null ? $"{reason} ({where})" : $"{message}: {reason} ({where})");
}
}
@@ -0,0 +1,18 @@
namespace ViaFerrea.Tests.Harness;
/// <summary>
/// Marca un metodo come test. Il metodo può essere statico o d'istanza (classe con costruttore
/// senza parametri), restituire void o Task.
/// </summary>
[AttributeUsage(AttributeTargets.Method, AllowMultiple = false)]
public sealed class TestAttribute : Attribute
{
/// <summary>Test lungo (simulazioni pluriennali): escluso con --skip-slow.</summary>
public bool Slow { get; init; }
/// <summary>Test che non può girare in parallelo con altri (porte di rete, processi figli).</summary>
public bool Isolated { get; init; }
/// <summary>Descrizione facoltativa mostrata in --list.</summary>
public string? Description { get; init; }
}
+120
View File
@@ -0,0 +1,120 @@
using System.Collections.Concurrent;
using System.Diagnostics;
using System.Reflection;
namespace ViaFerrea.Tests.Harness;
/// <summary>
/// Scopre i metodi [Test] per reflection e li esegue. Opzioni:
/// filtri liberi (sottostringa del nome), --list, --serial, --skip-slow.
/// Il codice di uscita è 0 solo se tutti i test selezionati passano.
/// </summary>
public static class TestRunner
{
private sealed record TestCase(string Name, MethodInfo Method, TestAttribute Attribute);
private sealed record TestOutcome(string Name, bool Passed, long Millis, string? Error);
public static int Run(string[] args, Assembly assembly)
{
bool list = args.Contains("--list");
bool serial = args.Contains("--serial");
bool skipSlow = args.Contains("--skip-slow");
var filters = args.Where(a => !a.StartsWith("--", StringComparison.Ordinal)).ToArray();
var tests = Discover(assembly)
.Where(t => filters.Length == 0 || filters.Any(f => t.Name.Contains(f, StringComparison.OrdinalIgnoreCase)))
.Where(t => !(skipSlow && t.Attribute.Slow))
.OrderBy(t => t.Name, StringComparer.Ordinal)
.ToList();
if (list)
{
foreach (var t in tests)
Console.WriteLine($"{t.Name}{(t.Attribute.Slow ? " [lento]" : "")}{(t.Attribute.Description is { } d ? " — " + d : "")}");
return 0;
}
Console.WriteLine($"Via Ferrea — {tests.Count} test selezionati");
var total = Stopwatch.StartNew();
var outcomes = new ConcurrentBag<TestOutcome>();
var parallel = tests.Where(t => !serial && !t.Attribute.Isolated).ToList();
var sequential = tests.Where(t => serial || t.Attribute.Isolated).ToList();
Parallel.ForEach(parallel, new ParallelOptions { MaxDegreeOfParallelism = Math.Max(1, Environment.ProcessorCount) },
t =>
{
var o = Execute(t);
Report(o);
outcomes.Add(o);
});
foreach (var t in sequential)
{
var o = Execute(t);
Report(o);
outcomes.Add(o);
}
var failed = outcomes.Where(o => !o.Passed).OrderBy(o => o.Name, StringComparer.Ordinal).ToList();
Console.WriteLine();
Console.WriteLine($"Eseguiti {outcomes.Count}, superati {outcomes.Count - failed.Count}, falliti {failed.Count} in {total.Elapsed.TotalSeconds:F1} s");
foreach (var f in failed)
Console.WriteLine($" FALLITO {f.Name}: {f.Error}");
return failed.Count == 0 && tests.Count > 0 ? 0 : 1;
}
private static readonly Lock ConsoleLock = new();
private static void Report(TestOutcome o)
{
lock (ConsoleLock)
{
if (o.Passed)
Console.WriteLine($" ok {o.Name} ({o.Millis} ms)");
else
Console.WriteLine($" FALLITO {o.Name} ({o.Millis} ms)\n {o.Error}");
}
}
private static IEnumerable<TestCase> Discover(Assembly assembly)
{
const BindingFlags flags = BindingFlags.Public | BindingFlags.NonPublic | BindingFlags.Static | BindingFlags.Instance | BindingFlags.DeclaredOnly;
foreach (var type in assembly.GetTypes())
{
foreach (var method in type.GetMethods(flags))
{
var attr = method.GetCustomAttribute<TestAttribute>();
if (attr is null) continue;
if (method.GetParameters().Length != 0)
throw new InvalidOperationException($"Il test {type.Name}.{method.Name} non deve avere parametri");
yield return new TestCase($"{type.Name}.{method.Name}", method, attr);
}
}
}
private static TestOutcome Execute(TestCase t)
{
var sw = Stopwatch.StartNew();
try
{
object? instance = t.Method.IsStatic ? null : Activator.CreateInstance(t.Method.DeclaringType!);
object? result = t.Method.Invoke(instance, null);
if (result is Task task) task.GetAwaiter().GetResult();
(instance as IDisposable)?.Dispose();
return new TestOutcome(t.Name, true, sw.ElapsedMilliseconds, null);
}
catch (TargetInvocationException ex) when (ex.InnerException is not null)
{
return new TestOutcome(t.Name, false, sw.ElapsedMilliseconds, Describe(ex.InnerException));
}
catch (Exception ex)
{
return new TestOutcome(t.Name, false, sw.ElapsedMilliseconds, Describe(ex));
}
}
private static string Describe(Exception ex) => ex is AssertionException
? ex.Message
: $"{ex.GetType().Name}: {ex.Message}\n{ex.StackTrace}";
}
+11
View File
@@ -0,0 +1,11 @@
using ViaFerrea.Tests.Harness;
namespace ViaFerrea.Tests;
/// <summary>
/// Punto d'ingresso unico: dotnet run --project tests/ViaFerrea.Tests [-- filtri] [--list] [--serial] [--skip-slow].
/// </summary>
public static class TestProgram
{
public static int Main(string[] args) => TestRunner.Run(args, typeof(TestProgram).Assembly);
}
@@ -0,0 +1,21 @@
<Project Sdk="Microsoft.NET.Sdk">
<!-- Harness di test interno: nessun framework esterno, si esegue con dotnet run. -->
<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>net10.0</TargetFramework>
<RootNamespace>ViaFerrea.Tests</RootNamespace>
</PropertyGroup>
<ItemGroup>
<ProjectReference Include="..\..\src\ViaFerrea.Core\ViaFerrea.Core.csproj" />
<ProjectReference Include="..\..\src\ViaFerrea.Protocol\ViaFerrea.Protocol.csproj" />
<ProjectReference Include="..\..\src\ViaFerrea.Server\ViaFerrea.Server.csproj" />
</ItemGroup>
<ItemGroup>
<Content Include="..\..\data\**\*.json" LinkBase="data" CopyToOutputDirectory="PreserveNewest" />
<Content Include="scenarios\**\*.json" CopyToOutputDirectory="PreserveNewest" />
</ItemGroup>
</Project>