- 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
360 lines
43 KiB
Markdown
360 lines
43 KiB
Markdown
# 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.
|