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>
43 KiB
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.mdaggiornato e un commitF<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.shfa fallire la build se compare unPackageReference. - 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:
longin 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 congodot --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.propsalla 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.Clientconproject.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=trueeProjectReferencea 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 viaworld.Rng.Fork("industries"); vietatiRandom,Guid.NewGuid,DateTime.Now,Environment.TickCountnella simulazione. - Stato in array e
Listordinati per id; mai iterareDictionary/HashSetper 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 daWorld.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 serviziospare_parts(ricambi, prodotti dalla fabbrica di macchinari) emachinery(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 conrequirements(netWorth, connectedTownsOver, creditRating) eunlocks(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 inbyte(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)eAspectper 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 mondialeW(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; oltrestorageDaysl'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; passeggeripax × baseFare × km^0.85 × classe(worker 1, staff 3);tfscende 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 dahTerrenopiù 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 rispettagMax. - 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
gMaxper 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 èUnderConstructionfinché 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) / Kcon K inconstruction.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 inStallede 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 hannoJobs { Workers, Staff }per livello; le città stesse offrono posti (servizi) per una quota della popolazione. - Ogni mese
EmploymentMatchercostruisce iCommuteContract { Town, Workplace, Category, Headcount, HomeStation, WorkStation, Route (linee e cambi), ExpectedMinutes, Carrier }:- per ogni posto scoperto cerca città con lavoratori liberi raggiungibili sul
LineGraphentro 60 minuti di orologio treni (personale: 90 minuti, solo città con servizi), includendo il tratto a piedi dentro il bacino; - ordina per tempo di viaggio; assegna in proporzione ai lavoratori liberi, non oltre la capacità residua stimata delle linee (posti per giorno);
- i contratti esistenti restano validi se il percorso esiste ancora.
- per ogni posto scoperto cerca città con lavoratori liberi raggiungibili sul
- 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/covStaffdell'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
c0–100. - Usura giornaliera per componente:
w = wBase × (kmGiorno/100) × (1 + 2·quotaPendenza) × (1 + 0.5·quotaAltaVelocità) × (1 + 0.3·carico) × ageFactor × difficoltà, conwBaseper 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 = 1fino alifeYears, +0.5 ogni 5 anni oltre. - Rischio di guasto giornaliero:
h = h0 × exp(0.8·(50 − c)/10)sec < 50, altrimentih0/4, conh0 = 0.002; il componente conhpiù 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 sec < 15ev > 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 = 40per ciascun componente con l'usura media degli ultimi 15 giorni;dueDate = min(scadenza da politica, stima − 5 giorni). - Sceglie il deposito con
tempoViaggio + attesaStimataminima 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
c0–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 = 1perc ≥ 70, lineare fino a 0.5 perc = 20, 0.3 sotto. - Rischio di fermo giornaliero
= 0.001 × exp((40 − c)/8)perc < 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_parts0 / 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; riportaca 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 < 35e 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)
AiCompanyAgentusa esclusivamente i comandi del protocollo (nessun accesso privilegiato allo stato). Pianificazione mensile:- genera candidati: coppie (sorgente, destinazione) non servite con margine stimato dagli stessi estimatori disponibili nei tooltip; città senza stazione; industrie con posti scoperti;
- per ogni candidato stima costo di costruzione con
TrackPlannersu un percorso trovato con Dijkstra sulla griglia delle celle (costo = costo di costruzione della cella + penalità pendenza), ricavi annui, ROI; - 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,sentiment0.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).
- 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). - 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.
- 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.
- 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).
- 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). - 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.
- 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.
- 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. HandshakeHello { protocolVersion, clientVersion, token }→Welcome { sessionId, worldSummary, dataHash, difficulty }oReject. - 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 unbyte 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, stampaLISTENING <porta>) e--healthcheck(GET su /health, exit 0/1). GameLoopsu thread dedicato con accumulatore (Stopwatch); se un tick supera il budget riduce la velocità effettiva e segnalaslow. Comandi daConcurrentQueuedrenata a inizio tick.SessionManager: WebSocket su/ws, token nell'Hello, coda di invio per sessione con backpressure, riconnessione consessionId.- 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). NetClientconClientWebSocket;LocalServerLauncheravviaserver/RailEnterprise.Server(.exe)con--local --token <guid>, leggeLISTENING <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
TrackProfilecon 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,AssertEqual/True/Throws/Approx, exit code); unico comandodotnet 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 riferimentotests/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
- 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.shescripts/test.shverdi 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.shescripts/test.sh; aggiornadocs/STATE.md(fatto, in corso, prossimo passo, versioni degli strumenti, misure di prestazione reali); commitF<n>: <cosa>. - Riepilogo in chat: cosa è stato fatto, decisioni con ADR, limiti noti, prossimo comando da darti.