Files
Rail_Enterprise/docs/GUIDA.md
T
Alby96andClaude Opus 5.5 c1a0049bcf
CI / Build e test (pull_request) Successful in 1m20s
CI / Immagine Docker (pull_request) Successful in 37s
Infrastruttura: nome «Rail Enterprise», CI e rilasci su Gitea, documentazione
Il progetto adotta il nome «Rail Enterprise» ovunque (codice RailEnterprise.*,
variabili RE_*, intestazioni RESV/RECL, immagine rail-enterprise-server) per
allinearsi al repository Gitea. Aggiunge Gitea Actions sul modello di Chronos:
CI su PR e main, rilascio da tag con gioco Windows (client Godot + server in
server/), server Windows/Linux e immagine Docker nel registro Gitea, nightly.
Aggiunge i riferimenti visivi 06–09, i modelli di PR e issue, l'ADR 0014 e
aggiorna README (comandi locali), STATE e CLAUDE.md. 120 test verdi.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-07 11:14:54 +01:00

360 lines
43 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# RAIL ENTERPRISE — Guida operativa per Claude Code (v2)
Sei lo sviluppatore principale di «Rail Enterprise», 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 `RailEnterprise.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 RailEnterprise
dotnet new classlib -n RailEnterprise.Core -o src/RailEnterprise.Core -f net10.0
dotnet new classlib -n RailEnterprise.Protocol -o src/RailEnterprise.Protocol -f net10.0
dotnet new web -n RailEnterprise.Server -o src/RailEnterprise.Server -f net10.0
dotnet new console -n RailEnterprise.Tools -o src/RailEnterprise.Tools -f net10.0
dotnet new console -n RailEnterprise.Tests -o tests/RailEnterprise.Tests -f net10.0
dotnet sln add src/RailEnterprise.Core src/RailEnterprise.Protocol src/RailEnterprise.Server src/RailEnterprise.Tools tests/RailEnterprise.Tests
dotnet add src/RailEnterprise.Protocol reference src/RailEnterprise.Core
dotnet add src/RailEnterprise.Server reference src/RailEnterprise.Core src/RailEnterprise.Protocol
dotnet add src/RailEnterprise.Tools reference src/RailEnterprise.Core src/RailEnterprise.Protocol
dotnet add tests/RailEnterprise.Tests reference src/RailEnterprise.Core src/RailEnterprise.Protocol src/RailEnterprise.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/RailEnterprise.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 RailEnterprise.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/ RailEnterprise.Core RailEnterprise.Protocol RailEnterprise.Server RailEnterprise.Tools
client/ RailEnterprise.Client (scenes/ scripts/ assets/fonts/ assets/i18n/ assets/theme/)
tests/ RailEnterprise.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 `railenterprise-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/RailEnterprise.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/RailEnterprise.Server`)
- Config da ambiente: `RE_PORT` (7400), `RE_TOKEN`, `RE_DATA_DIR` (/data), `RE_TICK_MS` (50), `RE_AUTOSAVE_MIN` (10), `RE_SEED`, `RE_MAP_SIZE`, `RE_DIFFICULTY`, `RE_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 `$RE_DATA_DIR/saves/` con rotazione degli ultimi 5. Log JSON su stdout.
### 14.3 Client Godot (`client/RailEnterprise.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/RailEnterprise.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/RailEnterprise.Server -c Release -o /app
FROM mcr.microsoft.com/dotnet/aspnet:10.0
WORKDIR /app
COPY --from=build /app .
RUN adduser --disabled-password --gecos "" rail && mkdir -p /data && chown rail /data
USER rail
ENV RE_PORT=7400 RE_DATA_DIR=/data ASPNETCORE_URLS=http://0.0.0.0:7400
EXPOSE 7400
VOLUME /data
HEALTHCHECK --interval=30s --timeout=5s CMD ["dotnet","RailEnterprise.Server.dll","--healthcheck"]
ENTRYPOINT ["dotnet","RailEnterprise.Server.dll"]
```
- `docker/docker-compose.yml`: servizio rail-enterprise, porta 7400:7400, volume ./data:/data, env RE_TOKEN e RE_DIFFICULTY, restart unless-stopped.
- `docker/unraid-template.xml`: Repository `<registry Gitea>/rail-enterprise-server:latest`, rete bridge, porta 7400, volume /mnt/user/appdata/rail-enterprise → /data, variabili RE_TOKEN e RE_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/RailEnterprise.Tests`: harness interno (`[Test]` via reflection, `Assert` Equal/True/Throws/Approx, exit code); unico comando `dotnet run --project tests/RailEnterprise.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/RailEnterprise.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.