F6: tutorial guidato della prima partita

Tutorial facoltativo che accompagna il giocatore dalla mappa alla prima
linea in servizio e poi a Mercato globale, Finanze e La tua scalata. È
un'esperienza del solo client: osserva ciò che il client già riceve
(entità della compagnia in ClientWorld, esiti riusciti dei comandi,
pannello aperto, camera, velocità, anteprime del tracciato), non invia
comandi e non decide regole; Core, Protocol, Server e salvataggi non
cambiano (ADR 0023).

- Copione in assets/tutorial/tutorial.json (19 passi, chiavi di testo
  per T(), elemento da evidenziare con ripiego, condizione osservabile),
  esportato con il gioco; testi italiani e inglesi in strings.csv.
- Logica pura senza Godot in scripts/Tutorial/Logic: copione con
  validazione, fatti, condizioni counter/panel/all/any, macchina a stati,
  avanzamento salvato; compilata anche dal progetto dei test (8 test).
- Riquadro non modale in basso a sinistra della mappa, contorno ambra
  animato, Avanti / Salta passo / Chiudi tutorial, F1 per nasconderlo o
  riaprirlo; nel menu la casella «Mostra il tutorial» (attiva alla prima
  partita) e l'opzione «Tutorial».
- Avanzamento per partita in user://settings.cfg, ripreso dopo il
  caricamento; il pilota automatico non crea il tutorial.

Refs #45.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Alby96andClaude Opus 5.5 committed 2026-11-08 14:21:12 +01:00
1 parent 7eec322202
commit ebe4308e75
21 files changed
+1524 -8

No files matched your search

@@ -677,3 +677,52 @@ una leva non oltre {0} (rimborsando {1}),,leverage no higher than {0} (by repayi
Per il gradino {0} serve un punteggio di {1}: {2}.,,To reach {0} you need a score of {1}: {2}.
In bancarotta non si possono chiedere prestiti,,Loans cannot be requested while bankrupt
Fido disponibile {0} su {1}. Tasso di un nuovo prestito: {2} fisso (base {3} + rating {4} {5}) per {6} anni.,,Available credit {0} of {1}. Rate of a new loan: {2} fixed (base {3} + rating {4} {5}) for {6} years.
Avanti,,Next
Salta passo,,Skip step
Chiudi tutorial,,Close tutorial
Tutorial,,Tutorial
Riduci o espandi il riquadro del tutorial,,Collapse or expand the tutorial box
Passo {0} di {1},,Step {0} of {1}
Fine,,Finish
Fatto,,Done
Il tutorial si riapre con F1 o dal menu,,Reopen the tutorial with F1 or from the menu
Mostra il tutorial,,Show the tutorial
Guida passo per passo alla prima linea: si chiude quando vuoi e si riapre con F1,,Step-by-step guide to your first line: close it whenever you like and reopen it with F1
Partita locale con il tutorial dal primo passo,,Local game with the tutorial from the first step
Benvenuto in Rail Enterprise,,Welcome to Rail Enterprise
"Guidi una compagnia ferroviaria: costruisci binari e stazioni, trasporti merci e pendolari e fai crescere il patrimonio fino a dominare il mercato. Questo tutorial ti accompagna nella prima linea; puoi saltare un passo o chiuderlo quando vuoi.",,"You run a railway company: build track and stations, carry goods and commuters and grow your net worth until you dominate the market. This tutorial walks you through your first line; you can skip a step or close it whenever you like."
Muovi la mappa,,Move the map
Trascina con il tasto destro (o usa WASD e le frecce) per spostarti e gira la rotella per lo zoom. Cerca una città e un'industria vicine: saranno le due stazioni della prima linea.,,Drag with the right mouse button (or use WASD and the arrow keys) to move and turn the wheel to zoom. Look for a town and an industry close to each other: they will be the two stations of your first line.
Il tempo,,Time
"In alto scegli la velocità del gioco: II mette in pausa, 1× – 8× accelerano. Anche la barra spaziatrice mette in pausa e riprende. Cambia la velocità per proseguire.",,"At the top you choose the game speed: II pauses, 1× – 8× speed it up. The space bar also pauses and resumes. Change the speed to continue."
Costruisci due stazioni,,Build two stations
Apri lo strumento Stazione e fai clic sulla mappa vicino a un'industria e poi vicino a una città. Il cerchio è il bacino di utenza: le merci e i passeggeri arrivano solo da lì.,,Open the Station tool and click the map near an industry and then near a town. The circle is the catchment area: goods and passengers only come from inside it.
Costruisci un deposito,,Build a depot
"Con lo strumento Deposito posa un deposito vicino a una delle stazioni. Nel deposito si comprano i veicoli, si compongono i treni e si fanno le manutenzioni.",,"With the Depot tool place a depot near one of the stations. In the depot you buy vehicles, compose trains and carry out maintenance."
Lo strumento Binari,,The Track tool
Apri lo strumento Binari: scegli la classe del binario e se ammettere ponti e gallerie.,,Open the Track tool: choose the track class and whether to allow bridges and tunnels.
Guarda il profilo e le opere,,Look at the profile and the structures
"Fai clic sulla prima stazione e muovi il mouse verso la seconda: il profilo mostra il terreno e la quota del binario. Sotto compaiono rilevati, trincee, ponti e gallerie con lunghezza, pendenza, costo e giorni di cantiere. Se attraversi un fiume vedrai il ponte.",,"Click the first station and move the mouse towards the second: the profile shows the terrain and the height of the track. Below it you see embankments, cuttings, bridges and tunnels with length, gradient, cost and days of work. If you cross a river you will see the bridge."
Costruisci il binario,,Build the track
"Aggiungi punti con altri clic per evitare salite ripide, poi premi Costruisci (o Invio). Il costo viene addebitato subito e il cantiere parte.",,"Add points with more clicks to avoid steep climbs, then press Build (or Enter). The cost is charged at once and construction starts."
Collega il deposito,,Connect the depot
"Il deposito deve essere raccordato alla linea: traccia un breve binario dal deposito alla stazione più vicina. Se è già collegato, premi Salta passo.",,"The depot must be connected to the line: lay a short track from the depot to the nearest station. If it is already connected, press Skip step."
Attendi i cantieri,,Wait for construction
I cantieri richiedono giorni di gioco: accelera il tempo e osserva il tratteggio dei lavori che diventa binario.,,Construction takes game days: speed up time and watch the dashed works turn into track.
Compra una locomotiva,,Buy a locomotive
"Apri Treni, scegli il deposito e una locomotiva dal catalogo, poi premi Compra veicoli.",,"Open Trains, choose the depot and a locomotive from the catalogue, then press Buy vehicles."
Compra i carri,,Buy the wagons
Ora compra qualche carro per la merce dell'industria (o carrozze per i pendolari): ogni carro accetta solo alcune merci.,,Now buy a few wagons for the industry's goods (or coaches for commuters): each wagon only accepts certain goods.
Componi il treno,,Compose the train
"Seleziona nell'elenco del deposito la locomotiva e i carri, nell'ordine in cui li vuoi, dai un nome al treno e premi Componi.",,"In the depot list select the locomotive and the wagons in the order you want, name the train and press Compose."
Crea una linea,,Create a line
Apri Linee e fai clic sulle due stazioni in ordine: sono le fermate. Scegli nome e colore e premi Crea linea.,,Open Lines and click the two stations in order: they are the stops. Choose a name and a colour and press Create line.
Assegna il treno alla linea,,Assign the train to the line
"Torna in Treni, seleziona il treno, scegli la linea e premi Assegna: il treno esce dal deposito e comincia il servizio.",,"Go back to Trains, select the train, choose the line and press Assign: the train leaves the depot and starts service."
Il Mercato globale,,The Global market
"Apri il Mercato: prezzi, offerta e domanda di ogni bene, la previsione e dove conviene vendere. Ti dice quali linee rendono di più.",,"Open the Market: prices, supply and demand of every good, the forecast and where it pays to sell. It tells you which lines earn the most."
Le Finanze,,Finances
"Apri le Finanze: conto economico per voce, rating e prestiti. Un prestito ben speso costruisce linee; troppi debiti abbassano il rating e alzano il tasso.",,"Open Finances: income statement by item, rating and loans. A well-spent loan builds lines; too much debt lowers the rating and raises the rate."
"Apri la Scalata (o fai clic sul livello in alto): i livelli della compagnia, che cosa sbloccano e che cosa manca per salire.",,"Open the Climb (or click the tier at the top): the company tiers, what they unlock and what is missing to move up."
Qualche consiglio,,A few tips
Collega industrie che producono a chi consuma la loro merce e porta i lavoratori dalle città alle industrie. Tieni d'occhio le Officine: un treno trascurato si guasta. Controlla cassa e rating prima di indebitarti. Buon viaggio! Puoi riaprire il tutorial con F1.,,Connect producing industries to those that consume their goods and bring workers from towns to industries. Keep an eye on the Workshops: a neglected train breaks down. Check cash and rating before borrowing. Have a good journey! You can reopen the tutorial with F1.
1 keys it en
677 Per il gradino {0} serve un punteggio di {1}: {2}. To reach {0} you need a score of {1}: {2}.
678 In bancarotta non si possono chiedere prestiti Loans cannot be requested while bankrupt
679 Fido disponibile {0} su {1}. Tasso di un nuovo prestito: {2} fisso (base {3} + rating {4} {5}) per {6} anni. Available credit {0} of {1}. Rate of a new loan: {2} fixed (base {3} + rating {4} {5}) for {6} years.
680 Avanti Next
681 Salta passo Skip step
682 Chiudi tutorial Close tutorial
683 Tutorial Tutorial
684 Riduci o espandi il riquadro del tutorial Collapse or expand the tutorial box
685 Passo {0} di {1} Step {0} of {1}
686 Fine Finish
687 Fatto Done
688 Il tutorial si riapre con F1 o dal menu Reopen the tutorial with F1 or from the menu
689 Mostra il tutorial Show the tutorial
690 Guida passo per passo alla prima linea: si chiude quando vuoi e si riapre con F1 Step-by-step guide to your first line: close it whenever you like and reopen it with F1
691 Partita locale con il tutorial dal primo passo Local game with the tutorial from the first step
692 Benvenuto in Rail Enterprise Welcome to Rail Enterprise
693 Guidi una compagnia ferroviaria: costruisci binari e stazioni, trasporti merci e pendolari e fai crescere il patrimonio fino a dominare il mercato. Questo tutorial ti accompagna nella prima linea; puoi saltare un passo o chiuderlo quando vuoi. You run a railway company: build track and stations, carry goods and commuters and grow your net worth until you dominate the market. This tutorial walks you through your first line; you can skip a step or close it whenever you like.
694 Muovi la mappa Move the map
695 Trascina con il tasto destro (o usa WASD e le frecce) per spostarti e gira la rotella per lo zoom. Cerca una città e un'industria vicine: saranno le due stazioni della prima linea. Drag with the right mouse button (or use WASD and the arrow keys) to move and turn the wheel to zoom. Look for a town and an industry close to each other: they will be the two stations of your first line.
696 Il tempo Time
697 In alto scegli la velocità del gioco: II mette in pausa, 1× – 8× accelerano. Anche la barra spaziatrice mette in pausa e riprende. Cambia la velocità per proseguire. At the top you choose the game speed: II pauses, 1× – 8× speed it up. The space bar also pauses and resumes. Change the speed to continue.
698 Costruisci due stazioni Build two stations
699 Apri lo strumento Stazione e fai clic sulla mappa vicino a un'industria e poi vicino a una città. Il cerchio è il bacino di utenza: le merci e i passeggeri arrivano solo da lì. Open the Station tool and click the map near an industry and then near a town. The circle is the catchment area: goods and passengers only come from inside it.
700 Costruisci un deposito Build a depot
701 Con lo strumento Deposito posa un deposito vicino a una delle stazioni. Nel deposito si comprano i veicoli, si compongono i treni e si fanno le manutenzioni. With the Depot tool place a depot near one of the stations. In the depot you buy vehicles, compose trains and carry out maintenance.
702 Lo strumento Binari The Track tool
703 Apri lo strumento Binari: scegli la classe del binario e se ammettere ponti e gallerie. Open the Track tool: choose the track class and whether to allow bridges and tunnels.
704 Guarda il profilo e le opere Look at the profile and the structures
705 Fai clic sulla prima stazione e muovi il mouse verso la seconda: il profilo mostra il terreno e la quota del binario. Sotto compaiono rilevati, trincee, ponti e gallerie con lunghezza, pendenza, costo e giorni di cantiere. Se attraversi un fiume vedrai il ponte. Click the first station and move the mouse towards the second: the profile shows the terrain and the height of the track. Below it you see embankments, cuttings, bridges and tunnels with length, gradient, cost and days of work. If you cross a river you will see the bridge.
706 Costruisci il binario Build the track
707 Aggiungi punti con altri clic per evitare salite ripide, poi premi Costruisci (o Invio). Il costo viene addebitato subito e il cantiere parte. Add points with more clicks to avoid steep climbs, then press Build (or Enter). The cost is charged at once and construction starts.
708 Collega il deposito Connect the depot
709 Il deposito deve essere raccordato alla linea: traccia un breve binario dal deposito alla stazione più vicina. Se è già collegato, premi Salta passo. The depot must be connected to the line: lay a short track from the depot to the nearest station. If it is already connected, press Skip step.
710 Attendi i cantieri Wait for construction
711 I cantieri richiedono giorni di gioco: accelera il tempo e osserva il tratteggio dei lavori che diventa binario. Construction takes game days: speed up time and watch the dashed works turn into track.
712 Compra una locomotiva Buy a locomotive
713 Apri Treni, scegli il deposito e una locomotiva dal catalogo, poi premi Compra veicoli. Open Trains, choose the depot and a locomotive from the catalogue, then press Buy vehicles.
714 Compra i carri Buy the wagons
715 Ora compra qualche carro per la merce dell'industria (o carrozze per i pendolari): ogni carro accetta solo alcune merci. Now buy a few wagons for the industry's goods (or coaches for commuters): each wagon only accepts certain goods.
716 Componi il treno Compose the train
717 Seleziona nell'elenco del deposito la locomotiva e i carri, nell'ordine in cui li vuoi, dai un nome al treno e premi Componi. In the depot list select the locomotive and the wagons in the order you want, name the train and press Compose.
718 Crea una linea Create a line
719 Apri Linee e fai clic sulle due stazioni in ordine: sono le fermate. Scegli nome e colore e premi Crea linea. Open Lines and click the two stations in order: they are the stops. Choose a name and a colour and press Create line.
720 Assegna il treno alla linea Assign the train to the line
721 Torna in Treni, seleziona il treno, scegli la linea e premi Assegna: il treno esce dal deposito e comincia il servizio. Go back to Trains, select the train, choose the line and press Assign: the train leaves the depot and starts service.
722 Il Mercato globale The Global market
723 Apri il Mercato: prezzi, offerta e domanda di ogni bene, la previsione e dove conviene vendere. Ti dice quali linee rendono di più. Open the Market: prices, supply and demand of every good, the forecast and where it pays to sell. It tells you which lines earn the most.
724 Le Finanze Finances
725 Apri le Finanze: conto economico per voce, rating e prestiti. Un prestito ben speso costruisce linee; troppi debiti abbassano il rating e alzano il tasso. Open Finances: income statement by item, rating and loans. A well-spent loan builds lines; too much debt lowers the rating and raises the rate.
726 Apri la Scalata (o fai clic sul livello in alto): i livelli della compagnia, che cosa sbloccano e che cosa manca per salire. Open the Climb (or click the tier at the top): the company tiers, what they unlock and what is missing to move up.
727 Qualche consiglio A few tips
728 Collega industrie che producono a chi consuma la loro merce e porta i lavoratori dalle città alle industrie. Tieni d'occhio le Officine: un treno trascurato si guasta. Controlla cassa e rating prima di indebitarti. Buon viaggio! Puoi riaprire il tutorial con F1. Connect producing industries to those that consume their goods and bring workers from towns to industries. Keep an eye on the Workshops: a neglected train breaks down. Check cash and rating before borrowing. Have a good journey! You can reopen the tutorial with F1.
@@ -0,0 +1,142 @@
{
"version": 1,
"steps": [
{
"id": "welcome",
"title": "Benvenuto in Rail Enterprise",
"text": "Guidi una compagnia ferroviaria: costruisci binari e stazioni, trasporti merci e pendolari e fai crescere il patrimonio fino a dominare il mercato. Questo tutorial ti accompagna nella prima linea; puoi saltare un passo o chiuderlo quando vuoi."
},
{
"id": "map",
"title": "Muovi la mappa",
"text": "Trascina con il tasto destro (o usa WASD e le frecce) per spostarti e gira la rotella per lo zoom. Cerca una città e un'industria vicine: saranno le due stazioni della prima linea.",
"highlight": "map",
"done": { "all": [ { "counter": "mapPan", "increase": 0.5 }, { "counter": "mapZoom", "increase": 0.5 } ] }
},
{
"id": "time",
"title": "Il tempo",
"text": "In alto scegli la velocità del gioco: II mette in pausa, 1× – 8× accelerano. Anche la barra spaziatrice mette in pausa e riprende. Cambia la velocità per proseguire.",
"highlight": "topbar:speed",
"done": { "counter": "speedChanges", "increase": 1 }
},
{
"id": "stations",
"title": "Costruisci due stazioni",
"text": "Apri lo strumento Stazione e fai clic sulla mappa vicino a un'industria e poi vicino a una città. Il cerchio è il bacino di utenza: le merci e i passeggeri arrivano solo da lì.",
"highlight": "toolbar:station",
"done": { "counter": "stations", "atLeast": 2 }
},
{
"id": "depot",
"title": "Costruisci un deposito",
"text": "Con lo strumento Deposito posa un deposito vicino a una delle stazioni. Nel deposito si comprano i veicoli, si compongono i treni e si fanno le manutenzioni.",
"highlight": "toolbar:depot",
"done": { "counter": "depots", "atLeast": 1 }
},
{
"id": "track-tool",
"title": "Lo strumento Binari",
"text": "Apri lo strumento Binari: scegli la classe del binario e se ammettere ponti e gallerie.",
"highlight": "toolbar:track",
"done": { "panel": "track" }
},
{
"id": "track-profile",
"title": "Guarda il profilo e le opere",
"text": "Fai clic sulla prima stazione e muovi il mouse verso la seconda: il profilo mostra il terreno e la quota del binario. Sotto compaiono rilevati, trincee, ponti e gallerie con lunghezza, pendenza, costo e giorni di cantiere. Se attraversi un fiume vedrai il ponte.",
"highlight": "track:profile",
"fallback": "toolbar:track",
"done": { "counter": "trackPreviews", "increase": 1 }
},
{
"id": "track-build",
"title": "Costruisci il binario",
"text": "Aggiungi punti con altri clic per evitare salite ripide, poi premi Costruisci (o Invio). Il costo viene addebitato subito e il cantiere parte.",
"highlight": "track:build",
"fallback": "toolbar:track",
"done": { "counter": "cmd:BuildTrack", "increase": 1 }
},
{
"id": "depot-link",
"title": "Collega il deposito",
"text": "Il deposito deve essere raccordato alla linea: traccia un breve binario dal deposito alla stazione più vicina. Se è già collegato, premi Salta passo.",
"highlight": "track:build",
"fallback": "toolbar:track",
"done": { "counter": "cmd:BuildTrack", "increase": 1 }
},
{
"id": "construction",
"title": "Attendi i cantieri",
"text": "I cantieri richiedono giorni di gioco: accelera il tempo e osserva il tratteggio dei lavori che diventa binario.",
"highlight": "topbar:speed",
"done": { "all": [ { "counter": "edges", "atLeast": 1 }, { "counter": "edgesBuilding", "atMost": 0 } ] }
},
{
"id": "locomotive",
"title": "Compra una locomotiva",
"text": "Apri Treni, scegli il deposito e una locomotiva dal catalogo, poi premi Compra veicoli.",
"highlight": "trains:buy",
"fallback": "toolbar:trains",
"done": { "counter": "locomotives", "atLeast": 1 }
},
{
"id": "cars",
"title": "Compra i carri",
"text": "Ora compra qualche carro per la merce dell'industria (o carrozze per i pendolari): ogni carro accetta solo alcune merci.",
"highlight": "trains:buy",
"fallback": "toolbar:trains",
"done": { "counter": "cars", "atLeast": 1 }
},
{
"id": "compose",
"title": "Componi il treno",
"text": "Seleziona nell'elenco del deposito la locomotiva e i carri, nell'ordine in cui li vuoi, dai un nome al treno e premi Componi.",
"highlight": "trains:compose",
"fallback": "toolbar:trains",
"done": { "counter": "trains", "atLeast": 1 }
},
{
"id": "line",
"title": "Crea una linea",
"text": "Apri Linee e fai clic sulle due stazioni in ordine: sono le fermate. Scegli nome e colore e premi Crea linea.",
"highlight": "lines:create",
"fallback": "toolbar:lines",
"done": { "counter": "lines", "atLeast": 1 }
},
{
"id": "assign",
"title": "Assegna il treno alla linea",
"text": "Torna in Treni, seleziona il treno, scegli la linea e premi Assegna: il treno esce dal deposito e comincia il servizio.",
"highlight": "trains:assign",
"fallback": "toolbar:trains",
"done": { "counter": "trainsOnLine", "atLeast": 1 }
},
{
"id": "market",
"title": "Il Mercato globale",
"text": "Apri il Mercato: prezzi, offerta e domanda di ogni bene, la previsione e dove conviene vendere. Ti dice quali linee rendono di più.",
"highlight": "toolbar:market",
"done": { "panel": "market" }
},
{
"id": "finance",
"title": "Le Finanze",
"text": "Apri le Finanze: conto economico per voce, rating e prestiti. Un prestito ben speso costruisce linee; troppi debiti abbassano il rating e alzano il tasso.",
"highlight": "toolbar:finance",
"done": { "panel": "finance" }
},
{
"id": "climb",
"title": "La tua scalata",
"text": "Apri la Scalata (o fai clic sul livello in alto): i livelli della compagnia, che cosa sbloccano e che cosa manca per salire.",
"highlight": "toolbar:climb",
"done": { "panel": "climb" }
},
{
"id": "tips",
"title": "Qualche consiglio",
"text": "Collega industrie che producono a chi consuma la loro merce e porta i lavoratori dalle città alle industrie. Tieni d'occhio le Officine: un treno trascurato si guasta. Controlla cassa e rating prima di indebitarti. Buon viaggio! Puoi riaprire il tutorial con F1."
}
]
}
@@ -6,7 +6,7 @@ runnable=true
dedicated_server=false
custom_features=""
export_filter="all_resources"
include_filter="data/*.json, data/schema/*.json, assets/i18n/*.csv, assets/fonts/*.ttf, assets/fonts/OFL.txt"
include_filter="data/*.json, data/schema/*.json, assets/i18n/*.csv, assets/tutorial/*.json, assets/fonts/*.ttf, assets/fonts/OFL.txt"
exclude_filter=""
export_path="export/windows/RailEnterprise.exe"
encryption_include_filters=""
@@ -36,7 +36,7 @@ runnable=true
dedicated_server=false
custom_features=""
export_filter="all_resources"
include_filter="data/*.json, data/schema/*.json, assets/i18n/*.csv, assets/fonts/*.ttf, assets/fonts/OFL.txt"
include_filter="data/*.json, data/schema/*.json, assets/i18n/*.csv, assets/tutorial/*.json, assets/fonts/*.ttf, assets/fonts/OFL.txt"
exclude_filter=""
export_path="export/linux/RailEnterprise.x86_64"
encrypt_pck=false
@@ -48,6 +48,9 @@ public partial class Toolbar : PanelContainer
}
}
/// <summary>Pulsante di uno strumento (per l'evidenziazione del tutorial).</summary>
public Control? ButtonFor(Tool tool) => _buttons.GetValueOrDefault(tool);
public void Select(Tool tool)
{
Current = tool;
@@ -27,6 +27,13 @@ public partial class TopBar : PanelContainer
private readonly ColorRect _serverDot = new() { CustomMinimumSize = new Vector2(10, 10) };
private readonly List<Button> _speeds = [];
private VBoxContainer? _tierBox;
private HBoxContainer? _speedBox;
/// <summary>Pulsanti della velocità (per l'evidenziazione del tutorial).</summary>
public Control? SpeedBox => _speedBox;
/// <summary>Livello e avanzamento (per l'evidenziazione del tutorial).</summary>
public Control? TierBox => _tierBox;
public override void _Ready()
{
@@ -66,6 +73,7 @@ public partial class TopBar : PanelContainer
speeds.AddChild(b);
}
row.AddChild(speeds);
_speedBox = speeds;
row.AddChild(new Control { SizeFlagsHorizontal = SizeFlags.ExpandFill });
row.AddChild(Stat(T("Cassa"), _cash));
row.AddChild(Stat(T("Patrimonio netto"), _worth));
+31 -2
View File
@@ -2,6 +2,7 @@ using Godot;
using RailEnterprise.Client.App;
using RailEnterprise.Client.Net;
using RailEnterprise.Client.Screens;
using RailEnterprise.Client.Tutorial;
using RailEnterprise.Core.Data;
using static RailEnterprise.Client.App.Localization;
@@ -18,6 +19,8 @@ public partial class Main : Node
private Node? _screen;
private GameSession? _session;
private string? _autopilot;
// tutorial della partita che si apre: casella del menu e opzione «Tutorial» (dal primo passo)
private bool _tutorialRequested, _tutorialRestart;
public override void _Ready()
{
@@ -59,8 +62,21 @@ public partial class Main : Node
private void ShowMenu(string status = "")
{
var menu = new MenuScreen();
menu.LocalGame += StartLocal;
menu.ConnectToServer += ShowConnect;
menu.LocalGame += () =>
{
SetTutorial(menu.ShowTutorial, restart: false);
StartLocal();
};
menu.ConnectToServer += () =>
{
SetTutorial(menu.ShowTutorial, restart: false);
ShowConnect();
};
menu.TutorialRequested += () =>
{
SetTutorial(true, restart: true);
StartLocal();
};
menu.LanguageChanged += code =>
{
var cfg = new ConfigFile();
@@ -74,6 +90,12 @@ public partial class Main : Node
if (status.Length > 0) menu.SetStatus(status);
}
private void SetTutorial(bool requested, bool restart)
{
_tutorialRequested = requested;
_tutorialRestart = restart;
}
private void ShowConnect()
{
var screen = new ConnectScreen();
@@ -136,7 +158,14 @@ public partial class Main : Node
if (s is not null) await s.DisposeAsync();
};
Swap(game);
// il pilota automatico non mostra il tutorial: le sue schermate restano quelle di sempre
if (_autopilot is not null) game.AddChild(new AutoPilot(game, _autopilot));
else
{
game.AddChild(new TutorialController(game, _tutorialRequested, _tutorialRestart));
TutorialSettings.Played = true;
_tutorialRestart = false;
}
}
public override void _Notification(int what)
@@ -29,6 +29,9 @@ public partial class LinesPanel : VBoxContainer
public event Action? StopsChanged;
/// <summary>Pulsante «Crea linea» (per l'evidenziazione del tutorial).</summary>
public Control? CreateButton { get; }
public LinesPanel(GameSession session)
{
_session = session;
@@ -54,6 +57,7 @@ public partial class LinesPanel : VBoxContainer
RefreshStops();
};
row.AddChild(create);
CreateButton = create;
row.AddChild(clear);
AddChild(row);
_status.AutowrapMode = TextServer.AutowrapMode.WordSmart;
@@ -27,6 +27,9 @@ public partial class TrackPanel : VBoxContainer
public Button Build { get; } = UiTheme.Primary(T("Costruisci"));
public Button Cancel { get; } = new() { Text = T("Annulla") };
/// <summary>Grafico del profilo (per l'evidenziazione del tutorial).</summary>
public Control Chart => _chart;
public event Action? OptionsChanged;
public TrackPanel(ClientWorld world)
@@ -34,6 +34,11 @@ public partial class TrainsPanel : VBoxContainer
public event Action<int>? TrainSelected;
/// <summary>Pulsanti di acquisto, composizione e assegnazione (per l'evidenziazione del tutorial).</summary>
public Control? BuyButton { get; }
public Control? ComposeButton { get; }
public Control? AssignButton { get; }
public TrainsPanel(GameSession session)
{
_session = session;
@@ -49,6 +54,7 @@ public partial class TrainsPanel : VBoxContainer
var buyButton = UiTheme.Primary(T("Compra veicoli"));
buyButton.Pressed += Buy;
AddChild(buyButton);
BuyButton = buyButton;
AddChild(UiTheme.Text(T("Veicoli liberi nel deposito (selezione multipla, in ordine)"), 13, Palette.TextSecondary));
AddChild(_inDepot);
var compose = PanelKit.Row();
@@ -57,6 +63,7 @@ public partial class TrainsPanel : VBoxContainer
var composeButton = new Button { Text = T("Componi") };
composeButton.Pressed += Compose;
compose.AddChild(composeButton);
ComposeButton = composeButton;
AddChild(compose);
AddChild(PanelKit.Separator());
AddChild(UiTheme.Text(T("Treni della compagnia"), 14, bold: true));
@@ -67,6 +74,7 @@ public partial class TrainsPanel : VBoxContainer
var assignButton = new Button { Text = T("Assegna") };
assignButton.Pressed += Assign;
assign.AddChild(assignButton);
AssignButton = assignButton;
AddChild(assign);
var home = new Button { Text = T("Manda al deposito") };
home.Pressed += SendHome;
@@ -45,6 +45,7 @@ public partial class GameScreen : Node
private MarketPanel? _market;
private ClimbPanel? _climb;
private FinancePanel? _finance;
private TrainsPanel? _trainsPanel;
// pannelli a tutto schermo (Compagnie e borsa, Mercato globale): coprono mappa e pannello destro, la barra resta
private readonly PanelContainer _full = new() { SizeFlagsHorizontal = Control.SizeFlags.ExpandFill, Visible = false };
private Control? _mapArea;
@@ -71,6 +72,12 @@ public partial class GameScreen : Node
public GameSession Session => _session;
public MapView Map => _map;
/// <summary>Strumento o pannello aperto dalla barra.</summary>
public Tool CurrentTool => _tool;
/// <summary>Anteprime del tracciato mostrate finora (il tutorial le usa per «guarda il profilo»).</summary>
public int TrackPreviews { get; private set; }
/// <summary>Seleziona uno strumento come dalla barra (anche per il pilota automatico).</summary>
public void UseTool(Tool tool) => _toolbar.Select(tool);
@@ -410,6 +417,7 @@ public partial class GameScreen : Node
_market = null;
_climb = null;
_finance = null;
_trainsPanel = null;
foreach (var c in _full.GetChildren()) c.QueueFree();
bool full = tool is Tool.Companies or Tool.Market or Tool.Climb or Tool.Finance;
_full.Visible = full;
@@ -438,7 +446,7 @@ public partial class GameScreen : Node
panel = new HelpPanel(T("Demolisci"), T("Clic su una stazione, un deposito o un binario libero per demolirlo; si recupera una parte del costo."));
break;
case Tool.Trains:
var trains = new TrainsPanel(_session);
var trains = _trainsPanel = new TrainsPanel(_session);
trains.TrainSelected += id =>
{
_map.Trains.SelectedTrain = id;
@@ -593,6 +601,7 @@ public partial class GameScreen : Node
try
{
_plan = _session.World.PreviewTrack(TrackCommand(pts, 0));
TrackPreviews++;
_trackPanel.Show(_plan);
_trackPanel.SetStatus("");
}
@@ -760,6 +769,37 @@ public partial class GameScreen : Node
return null;
}
// ------------------------------------------------------------------ tutorial
/// <summary>
/// Controllo dell'interfaccia che corrisponde a un elemento del tutorial (vedi
/// <c>TutorialScript.KnownTargets</c>); null se in questo momento non c'è (pannello chiuso).
/// </summary>
public Control? TutorialTarget(string id) => id switch
{
"map" => _mapArea,
"side" => _side,
"full" => _full,
"topbar:speed" => _top.SpeedBox,
"topbar:tier" => _top.TierBox,
"track:profile" => _trackPanel?.Chart,
"track:build" => _trackPanel?.Build,
"trains:buy" => _trainsPanel?.BuyButton,
"trains:compose" => _trainsPanel?.ComposeButton,
"trains:assign" => _trainsPanel?.AssignButton,
"lines:create" => _linesPanel?.CreateButton,
_ when id.StartsWith("toolbar:", StringComparison.Ordinal)
&& Enum.TryParse<Tool>(id["toolbar:".Length..], ignoreCase: true, out var tool) => _toolbar.ButtonFor(tool),
_ => null,
};
/// <summary>Area libera per il riquadro del tutorial: la mappa, o il pannello a tutto schermo se aperto.</summary>
public Rect2 TutorialArea()
{
if (_mapArea is { } map && map.IsVisibleInTree()) return map.GetGlobalRect();
return _full.Visible ? _full.GetGlobalRect() : new Rect2();
}
// ------------------------------------------------------------------ Cronaca finale e osservatore
/// <summary>Mostra la Cronaca quando arriva: subito se la partita è finita, oppure se l'ha chiesta il giocatore.</summary>
@@ -1,15 +1,25 @@
using Godot;
using RailEnterprise.Client.App;
using RailEnterprise.Client.Tutorial;
using static RailEnterprise.Client.App.Localization;
namespace RailEnterprise.Client.Screens;
/// <summary>Menu iniziale: partita locale (server figlio), collegamento a un server, lingua, uscita.</summary>
/// <summary>
/// Menu iniziale: partita locale (server figlio), collegamento a un server, tutorial, lingua, uscita. La
/// casella «Mostra il tutorial» è attiva alla prima partita; «Tutorial» apre la partita locale con il
/// tutorial dal primo passo.
/// </summary>
public partial class MenuScreen : Control
{
public event Action? LocalGame;
public event Action? ConnectToServer;
public event Action<string>? LanguageChanged;
public event Action? TutorialRequested;
private readonly CheckBox _showTutorial = new() { Text = T("Mostra il tutorial") };
/// <summary>Casella «Mostra il tutorial» per la partita che si apre.</summary>
public bool ShowTutorial => _showTutorial.ButtonPressed;
private readonly Label _status = UiTheme.Text("", 14, Palette.TextSecondary);
public override void _Ready()
@@ -33,9 +43,16 @@ public partial class MenuScreen : Control
local.CustomMinimumSize = new Vector2(0, 48);
local.Pressed += () => LocalGame?.Invoke();
col.AddChild(local);
_showTutorial.ButtonPressed = !TutorialSettings.Played;
_showTutorial.TooltipText = T("Guida passo per passo alla prima linea: si chiude quando vuoi e si riapre con F1");
col.AddChild(_showTutorial);
var remote = new Button { Text = T("Collegati a un server"), CustomMinimumSize = new Vector2(0, 48) };
remote.Pressed += () => ConnectToServer?.Invoke();
col.AddChild(remote);
var tutorial = new Button { Text = T("Tutorial"), CustomMinimumSize = new Vector2(0, 40) };
tutorial.TooltipText = T("Partita locale con il tutorial dal primo passo");
tutorial.Pressed += () => TutorialRequested?.Invoke();
col.AddChild(tutorial);
var lang = new HBoxContainer();
lang.AddThemeConstantOverride("separation", 8);
foreach (var (code, label) in new[] { ("it", "Italiano"), ("en", "English") })
@@ -0,0 +1,159 @@
namespace RailEnterprise.Client.Tutorial;
/// <summary>Stato del tutorial di una partita.</summary>
public enum TutorialStatus
{
/// <summary>In corso su un passo.</summary>
Active,
/// <summary>Tutti i passi completati o saltati.</summary>
Completed,
/// <summary>Chiuso dal giocatore prima della fine.</summary>
Closed,
}
/// <summary>Cosa fare all'apertura di una partita (vedi <see cref="TutorialMachine.Plan"/>).</summary>
public enum TutorialLaunch
{
/// <summary>Nessun tutorial.</summary>
Hidden,
/// <summary>Dal primo passo.</summary>
StartFresh,
/// <summary>Dal passo salvato.</summary>
Resume,
}
/// <summary>
/// Avanzamento salvato nelle impostazioni del client (una voce per partita): passo corrente e stato.
/// Il testo è <c>active:&lt;id&gt;</c>, <c>completed</c> o <c>closed</c>.
/// </summary>
public readonly record struct TutorialProgress(string? StepId, TutorialStatus Status)
{
public string Encode() => Status switch
{
TutorialStatus.Active => "active:" + (StepId ?? ""),
TutorialStatus.Completed => "completed",
_ => "closed",
};
/// <summary>
/// Chiave della partita nelle impostazioni: seme, impronta del terreno e compagnia del giocatore, che il
/// client riceve nel Welcome. Resta la stessa dopo un salvataggio e un caricamento della stessa partita.
/// </summary>
public static string GameKey(ulong seed, ulong terrainHash, int companyId) => $"g_{seed:x16}_{terrainHash:x16}_{companyId}";
/// <summary>Legge una voce salvata; null se vuota o non riconosciuta.</summary>
public static TutorialProgress? Decode(string? text)
{
if (string.IsNullOrWhiteSpace(text)) return null;
text = text.Trim();
if (text == "completed") return new TutorialProgress(null, TutorialStatus.Completed);
if (text == "closed") return new TutorialProgress(null, TutorialStatus.Closed);
if (text.StartsWith("active:", StringComparison.Ordinal))
{
string id = text["active:".Length..];
return new TutorialProgress(id.Length > 0 ? id : null, TutorialStatus.Active);
}
return null;
}
}
/// <summary>
/// Macchina a stati dei passi: un passo alla volta, completato quando la sua condizione è vera sui fatti
/// osservati (<see cref="Update"/>), oppure con Avanti (passi informativi), Salta passo o Chiudi. I contatori
/// con <c>increase</c> si confrontano con i fatti al primo aggiornamento del passo. Non decide regole di
/// gioco: guarda soltanto ciò che il client ha già ricevuto.
/// </summary>
public sealed class TutorialMachine
{
private TutorialFacts? _baseline;
public TutorialMachine(TutorialScript script)
{
if (script.Steps.Count == 0) throw new ArgumentException("Copione del tutorial senza passi", nameof(script));
Script = script;
}
public TutorialScript Script { get; }
/// <summary>Indice del passo corrente (uguale al numero di passi a tutorial completato).</summary>
public int Index { get; private set; }
public TutorialStatus Status { get; private set; } = TutorialStatus.Active;
public TutorialStep? Current => Status == TutorialStatus.Active && Index < Script.Steps.Count ? Script.Steps[Index] : null;
public bool IsLast => Index == Script.Steps.Count - 1;
/// <summary>Avanzamento da salvare.</summary>
public TutorialProgress Progress => new(Current?.Id, Status);
/// <summary>
/// Decide se mostrare il tutorial all'apertura di una partita. <paramref name="restart"/> (opzione «Tutorial»
/// del menu) riparte sempre dal primo passo; un tutorial in corso in quella partita si riprende; uno
/// completato o chiuso resta nascosto; senza voce salvata si mostra solo se il giocatore l'ha chiesto
/// (casella «Mostra il tutorial», attiva alla prima partita).
/// </summary>
public static TutorialLaunch Plan(bool requested, bool restart, TutorialProgress? saved)
{
if (restart) return TutorialLaunch.StartFresh;
if (saved is { } s) return s.Status == TutorialStatus.Active ? TutorialLaunch.Resume : TutorialLaunch.Hidden;
return requested ? TutorialLaunch.StartFresh : TutorialLaunch.Hidden;
}
/// <summary>Riparte dal primo passo.</summary>
public void Restart() => GoTo(0);
/// <summary>Riprende da un avanzamento salvato; un passo che non c'è più fa ripartire dall'inizio.</summary>
public void Restore(TutorialProgress progress)
{
switch (progress.Status)
{
case TutorialStatus.Active:
GoTo(Math.Max(0, Script.IndexOf(progress.StepId)));
break;
case TutorialStatus.Completed:
Index = Script.Steps.Count;
Status = TutorialStatus.Completed;
break;
default:
Status = TutorialStatus.Closed;
break;
}
}
/// <summary>Valuta il passo corrente sui fatti; se la condizione è vera passa al successivo e restituisce true.</summary>
public bool Update(TutorialFacts facts)
{
if (Current is not { } step) return false;
_baseline ??= facts.Clone();
if (step.Done is null || !step.Done.IsMet(facts, _baseline)) return false;
Advance();
return true;
}
/// <summary>Avanti: chiude un passo informativo (sugli altri equivale a <see cref="Skip"/>).</summary>
public void Next() => Advance();
/// <summary>Salta il passo corrente.</summary>
public void Skip() => Advance();
/// <summary>Chiude il tutorial; si potrà riaprire dal menu.</summary>
public void Close()
{
if (Status == TutorialStatus.Active) Status = TutorialStatus.Closed;
_baseline = null;
}
private void Advance()
{
if (Status != TutorialStatus.Active) return;
GoTo(Index + 1);
}
private void GoTo(int index)
{
_baseline = null;
Index = Math.Clamp(index, 0, Script.Steps.Count);
Status = Index >= Script.Steps.Count ? TutorialStatus.Completed : TutorialStatus.Active;
}
}
@@ -0,0 +1,205 @@
using System.Text.Json;
using System.Text.Json.Serialization;
using RailEnterprise.Core.Commands;
namespace RailEnterprise.Client.Tutorial;
/// <summary>
/// Copione del tutorial guidato (<c>assets/tutorial/tutorial.json</c>, ADR 0023): l'elenco ordinato dei
/// passi. È un file dati del client, non del motore: non cambia regole né salvataggi. Questa classe e le
/// altre di <c>Tutorial/Logic</c> non dipendono da Godot e si provano nel harness dei test.
/// </summary>
public sealed class TutorialScript
{
/// <summary>Versione del formato del file (oggi 1).</summary>
public int Version { get; init; } = 1;
public List<TutorialStep> Steps { get; init; } = [];
/// <summary>Indice del passo con l'id indicato, -1 se non c'è.</summary>
public int IndexOf(string? id) => id is null ? -1 : Steps.FindIndex(s => s.Id == id);
/// <summary>Legge il copione dal testo JSON (commenti e virgole finali ammessi, campi sconosciuti rifiutati).</summary>
public static TutorialScript Parse(string json) =>
JsonSerializer.Deserialize(json, TutorialJsonContext.Default.TutorialScript)
?? throw new JsonException("Copione del tutorial vuoto");
/// <summary>
/// Elementi dell'interfaccia che un passo può evidenziare. Il client li risolve nei controlli
/// (<c>GameScreen.TutorialTarget</c>); se un elemento non è visibile in quel momento si usa il
/// ripiego del passo, altrimenti non si evidenzia nulla.
/// </summary>
public static readonly IReadOnlyList<string> KnownTargets = BuildTargets();
private static List<string> BuildTargets()
{
var list = new List<string> { "map", "side", "full", "topbar:speed", "topbar:tier", "track:profile", "track:build", "trains:buy", "trains:compose", "trains:assign", "lines:create" };
foreach (string panel in TutorialFacts.KnownPanels)
{
if (panel != TutorialFacts.NoPanel) list.Add("toolbar:" + panel);
}
return list;
}
/// <summary>Controlla il copione: id unici, testi presenti, elementi, contatori e pannelli noti. Restituisce gli errori in italiano.</summary>
public List<string> Validate()
{
var errors = new List<string>();
if (Version != 1) errors.Add($"versione {Version} non supportata");
if (Steps.Count == 0) errors.Add("nessun passo");
var ids = new HashSet<string>(StringComparer.Ordinal);
foreach (var step in Steps)
{
string where = $"passo «{step.Id}»";
if (string.IsNullOrWhiteSpace(step.Id)) errors.Add("passo senza id");
else if (!ids.Add(step.Id)) errors.Add($"{where}: id ripetuto");
if (string.IsNullOrWhiteSpace(step.Title)) errors.Add($"{where}: titolo vuoto");
if (string.IsNullOrWhiteSpace(step.Text)) errors.Add($"{where}: testo vuoto");
if (step.Highlight is { } h && !KnownTargets.Contains(h)) errors.Add($"{where}: elemento da evidenziare sconosciuto «{h}»");
if (step.Fallback is { } f && !KnownTargets.Contains(f)) errors.Add($"{where}: ripiego sconosciuto «{f}»");
if (step.Fallback is not null && step.Highlight is null) errors.Add($"{where}: ripiego senza elemento principale");
step.Done?.Validate(where, errors);
}
return errors;
}
}
/// <summary>Passo del tutorial: testi (chiavi di traduzione), elemento da evidenziare, condizione di completamento.</summary>
public sealed class TutorialStep
{
public required string Id { get; init; }
/// <summary>Chiave del titolo per <c>T()</c> (testo italiano).</summary>
public required string Title { get; init; }
/// <summary>Chiave del testo per <c>T()</c> (testo italiano).</summary>
public required string Text { get; init; }
/// <summary>Elemento dell'interfaccia da evidenziare (vedi <see cref="TutorialScript.KnownTargets"/>), facoltativo.</summary>
public string? Highlight { get; init; }
/// <summary>Elemento da evidenziare quando il principale non è visibile (per esempio il pulsante che apre il pannello).</summary>
public string? Fallback { get; init; }
/// <summary>Condizione osservabile che completa il passo; senza condizione il passo è informativo (pulsante Avanti).</summary>
public TutorialCondition? Done { get; init; }
[JsonIgnore]
public bool IsInformative => Done is null;
}
/// <summary>
/// Condizione di completamento, valutata su fatti semplici che il client osserva (<see cref="TutorialFacts"/>).
/// Ha una sola forma tra: contatore (<c>counter</c> con <c>atLeast</c>, <c>atMost</c> e/o <c>increase</c>),
/// pannello aperto (<c>panel</c>), tutte (<c>all</c>) o almeno una (<c>any</c>) di altre condizioni.
/// <c>increase</c> confronta il contatore con il suo valore all'inizio del passo.
/// </summary>
public sealed class TutorialCondition
{
public string? Counter { get; init; }
public double? AtLeast { get; init; }
public double? AtMost { get; init; }
public double? Increase { get; init; }
public string? Panel { get; init; }
public List<TutorialCondition>? All { get; init; }
public List<TutorialCondition>? Any { get; init; }
/// <summary>Vera se i fatti di adesso soddisfano la condizione; <paramref name="baseline"/> sono i fatti all'inizio del passo.</summary>
public bool IsMet(TutorialFacts now, TutorialFacts baseline)
{
if (All is not null) return All.TrueForAll(c => c.IsMet(now, baseline));
if (Any is not null) return Any.Exists(c => c.IsMet(now, baseline));
if (Panel is not null) return now.Panel == Panel;
if (Counter is null) return false;
double value = now.Get(Counter);
if (AtLeast is { } min && value < min) return false;
if (AtMost is { } max && value > max) return false;
if (Increase is { } inc && value - baseline.Get(Counter) < inc) return false;
return true;
}
internal void Validate(string where, List<string> errors)
{
int forms = (Counter is not null ? 1 : 0) + (Panel is not null ? 1 : 0) + (All is not null ? 1 : 0) + (Any is not null ? 1 : 0);
if (forms != 1)
{
errors.Add($"{where}: la condizione deve avere una sola forma tra counter, panel, all e any");
return;
}
if (Counter is not null)
{
if (AtLeast is null && AtMost is null && Increase is null) errors.Add($"{where}: contatore «{Counter}» senza atLeast, atMost o increase");
if (!TutorialFacts.IsKnownCounter(Counter)) errors.Add($"{where}: contatore sconosciuto «{Counter}»");
}
else if (AtLeast is not null || AtMost is not null || Increase is not null)
{
errors.Add($"{where}: atLeast, atMost e increase valgono solo con counter");
}
if (Panel is not null && !TutorialFacts.KnownPanels.Contains(Panel)) errors.Add($"{where}: pannello sconosciuto «{Panel}»");
foreach (var list in new[] { All, Any })
{
if (list is null) continue;
if (list.Count == 0) errors.Add($"{where}: elenco di condizioni vuoto");
foreach (var c in list) c.Validate(where, errors);
}
}
}
/// <summary>Fatti osservati dal client: contatori (entità della compagnia, comandi riusciti, azioni sulla mappa) e pannello aperto.</summary>
public sealed class TutorialFacts
{
/// <summary>Pannello «nessuno» (barra degli strumenti senza selezione).</summary>
public const string NoPanel = "none";
/// <summary>Prefisso dei contatori dei comandi riusciti: <c>cmd:</c> + nome di <see cref="CommandType"/>.</summary>
public const string CommandPrefix = "cmd:";
/// <summary>Pannelli della barra degli strumenti, con i nomi in minuscolo dell'enumerazione <c>Hud.Tool</c>.</summary>
public static readonly IReadOnlyList<string> KnownPanels =
[
NoPanel, "track", "station", "signal", "depot", "trains", "lines", "maintenance", "employment", "industries", "market", "companies", "climb", "finance", "demolish",
];
/// <summary>
/// Contatori osservati: entità della compagnia nella copia locale (stazioni, depositi, archi, archi in
/// funzione, archi in cantiere, locomotive, carri e carrozze, treni, linee, treni in linea), azioni del
/// giocatore sulla mappa (spostamento in schermate, zoom in unità logaritmiche, cambi di velocità) e
/// anteprime valide del tracciato.
/// </summary>
public static readonly IReadOnlyList<string> KnownCounters =
[
"stations", "depots", "edges", "edgesActive", "edgesBuilding", "locomotives", "cars", "trains", "lines", "trainsOnLine",
"mapPan", "mapZoom", "speedChanges", "trackPreviews",
];
public Dictionary<string, double> Counters { get; } = new(StringComparer.Ordinal);
public string Panel { get; set; } = NoPanel;
public double Get(string counter) => Counters.TryGetValue(counter, out double v) ? v : 0;
public void Set(string counter, double value) => Counters[counter] = value;
public void Add(string counter, double amount) => Counters[counter] = Get(counter) + amount;
/// <summary>Nome del contatore di un tipo di comando riuscito.</summary>
public static string CommandCounter(CommandType type) => CommandPrefix + type;
public static bool IsKnownCounter(string name) =>
KnownCounters.Contains(name)
|| (name.StartsWith(CommandPrefix, StringComparison.Ordinal) && Enum.TryParse<CommandType>(name[CommandPrefix.Length..], ignoreCase: false, out var t)
&& Enum.IsDefined(t) && t.ToString() == name[CommandPrefix.Length..]);
public TutorialFacts Clone()
{
var copy = new TutorialFacts { Panel = Panel };
foreach (var (k, v) in Counters) copy.Counters[k] = v;
return copy;
}
}
[JsonSourceGenerationOptions(PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase, PropertyNameCaseInsensitive = true,
UnmappedMemberHandling = JsonUnmappedMemberHandling.Disallow, ReadCommentHandling = JsonCommentHandling.Skip,
AllowTrailingCommas = true)]
[JsonSerializable(typeof(TutorialScript))]
internal sealed partial class TutorialJsonContext : JsonSerializerContext;
@@ -0,0 +1,266 @@
using Godot;
using RailEnterprise.Client.Screens;
using RailEnterprise.Core.Commands;
using RailEnterprise.Core.Data;
using RailEnterprise.Core.Rail;
using RailEnterprise.Protocol;
using RailEnterprise.Protocol.Messages;
using static RailEnterprise.Client.App.Localization;
namespace RailEnterprise.Client.Tutorial;
/// <summary>
/// Collega il tutorial alla partita: raccoglie i fatti che il client osserva (entità della compagnia nella
/// copia locale, esiti dei comandi, pannello aperto, camera, velocità, anteprime del tracciato), fa avanzare
/// <see cref="TutorialMachine"/>, aggiorna <see cref="TutorialOverlay"/> e salva l'avanzamento per partita.
/// Non invia comandi e non decide regole. F1 riapre o nasconde il tutorial.
/// </summary>
public partial class TutorialController : Node
{
private const string ScriptPath = "res://assets/tutorial/tutorial.json";
private const double FactsInterval = 0.2;
private readonly GameScreen _game;
private bool _requested;
private bool _restart;
private readonly CanvasLayer _layer = new() { Layer = 3 };
private readonly TutorialOverlay _overlay = new();
private readonly TutorialFacts _facts = new();
private readonly Dictionary<string, VehicleKind> _vehicleKinds = [];
private TutorialMachine? _machine;
private string _gameKey = "";
private bool _visible;
private int _shownIndex = -1;
private double _sinceFacts = FactsInterval;
private Vector2? _lastCamera;
private float _lastZoom;
private byte? _lastSpeed;
/// <param name="requested">casella «Mostra il tutorial» del menu</param>
/// <param name="restart">opzione «Tutorial» del menu: dal primo passo anche se già fatto</param>
public TutorialController(GameScreen game, bool requested, bool restart)
{
_game = game;
_requested = requested;
_restart = restart;
}
public override void _Ready()
{
try
{
using var file = Godot.FileAccess.Open(ScriptPath, Godot.FileAccess.ModeFlags.Read)
?? throw new FileNotFoundException(ScriptPath);
var script = TutorialScript.Parse(file.GetAsText());
var errors = script.Validate();
if (errors.Count > 0) throw new InvalidDataException(string.Join("; ", errors));
_machine = new TutorialMachine(script);
}
catch (Exception e)
{
GD.PushWarning($"Tutorial non disponibile: {e.Message}");
return;
}
foreach (var v in _game.Session.World.Data.Vehicles) _vehicleKinds[v.Id] = v.Kind;
AddChild(_layer);
_layer.AddChild(_overlay);
_overlay.NextPressed += () => Act(m => m.Next());
_overlay.SkipPressed += () => Act(m => m.Skip());
_overlay.ClosePressed += () => Act(m => m.Close());
_game.Session.MessageApplied += OnMessage;
OpenForGame();
}
public override void _ExitTree() => _game.Session.MessageApplied -= OnMessage;
/// <summary>All'avvio e a ogni Welcome (nuova partita, caricamento): chiave della partita e piano di apertura.</summary>
private void OpenForGame()
{
if (_machine is null || _game.Session.World.Summary is not { } s) return;
_gameKey = TutorialProgress.GameKey(s.Seed, s.TerrainHash, s.CompanyId);
var saved = TutorialSettings.Read(_gameKey);
switch (TutorialMachine.Plan(_requested, _restart, saved))
{
case TutorialLaunch.StartFresh:
_machine.Restart();
Save();
_visible = true;
break;
case TutorialLaunch.Resume:
_machine.Restore(saved!.Value);
_visible = true;
break;
default:
if (saved is { } p) _machine.Restore(p);
else _machine.Close();
_visible = false;
break;
}
// casella e opzione del menu valgono per la partita aperta, non per le successive (Nuova partita+)
_requested = _restart = false;
_lastCamera = null;
_lastSpeed = null;
_shownIndex = -1;
Refresh();
}
private void OnMessage(IMessage message)
{
switch (message)
{
case Welcome:
OpenForGame();
break;
case CommandResultMessage { Ok: true } r:
_facts.Add(TutorialFacts.CommandCounter((CommandType)r.Type), 1);
break;
}
}
private void Act(Action<TutorialMachine> action)
{
if (_machine is null) return;
action(_machine);
Save();
if (_machine.Status != TutorialStatus.Active) _visible = false;
Refresh();
}
private void Save()
{
if (_machine is not null && _gameKey.Length > 0) TutorialSettings.Save(_gameKey, _machine.Progress);
}
public override void _UnhandledKeyInput(InputEvent e)
{
if (_machine is null || e is not InputEventKey { Pressed: true, Echo: false, Keycode: Key.F1 }) return;
if (_visible)
{
// F1 nasconde soltanto: il tutorial in corso resta salvato
_visible = false;
}
else
{
// riapre dal passo salvato, o dall'inizio se era chiuso o completato
if (_machine.Status != TutorialStatus.Active) _machine.Restart();
_visible = true;
_shownIndex = -1;
Save();
}
Refresh();
GetViewport().SetInputAsHandled();
}
public override void _Process(double delta)
{
if (_machine is null) return;
TrackCameraAndSpeed();
_sinceFacts += delta;
if (_sinceFacts >= FactsInterval)
{
_sinceFacts = 0;
CollectWorldFacts();
if (_visible)
{
string? title = _machine.Current is { } step ? T(step.Title) : null;
if (_machine.Update(_facts))
{
Save();
if (title is not null) _overlay.Flash(title);
// completato l'ultimo passo il riquadro si chiude
if (_machine.Status != TutorialStatus.Active) _visible = false;
}
}
}
Refresh();
}
/// <summary>Spostamento della camera (in schermate), zoom (in logaritmi) e cambi di velocità, sommati.</summary>
private void TrackCameraAndSpeed()
{
var map = _game.Map;
var camera = map.Camera.Position;
float zoom = map.Zoom;
if (_lastCamera is { } last && zoom > 0 && _lastZoom > 0)
{
if (Math.Abs(zoom - _lastZoom) > 1e-6)
{
// lo zoom attorno al cursore sposta anche la camera: non è uno spostamento
_facts.Add("mapZoom", Math.Abs(Math.Log(zoom / _lastZoom)));
}
else
{
float screen = map.GetViewportRect().Size.X / zoom;
if (screen > 0) _facts.Add("mapPan", camera.DistanceTo(last) / screen);
}
}
_lastCamera = camera;
_lastZoom = zoom;
var w = _game.Session.World;
byte speed = _game.Session.RequestedSpeed ?? w.LastDigest?.Speed ?? w.Speed;
if (_lastSpeed is { } s && s != speed) _facts.Add("speedChanges", 1);
_lastSpeed = speed;
}
/// <summary>Entità della compagnia nella copia locale, pannello aperto, anteprime del tracciato.</summary>
private void CollectWorldFacts()
{
var w = _game.Session.World;
int me = w.Summary?.CompanyId ?? -1;
int edges = 0, active = 0, locos = 0, cars = 0, trains = 0, onLine = 0;
foreach (var e in w.Edges.Values)
{
if (e.Owner != me) continue;
edges++;
if (e.State == (byte)EdgeState.Active) active++;
}
foreach (var v in w.Vehicles.Values)
{
if (v.Owner != me || !_vehicleKinds.TryGetValue(v.Type, out var kind)) continue;
if (kind == VehicleKind.Locomotive) locos++;
else cars++;
}
foreach (var t in w.Trains.Values)
{
if (t.Owner != me) continue;
trains++;
if (t.Line >= 0) onLine++;
}
_facts.Set("stations", w.Stations.Values.Count(s => s.Owner == me));
_facts.Set("depots", w.Depots.Values.Count(d => d.Owner == me));
_facts.Set("edges", edges);
_facts.Set("edgesActive", active);
// i cantieri sono gli archi non ancora in funzione (dismessi compresi: non bloccano un tutorial nuovo)
_facts.Set("edgesBuilding", w.Edges.Values.Count(e => e.Owner == me && e.State == (byte)EdgeState.UnderConstruction));
_facts.Set("locomotives", locos);
_facts.Set("cars", cars);
_facts.Set("trains", trains);
_facts.Set("lines", w.Lines.Values.Count(l => l.Owner == me));
_facts.Set("trainsOnLine", onLine);
_facts.Set("trackPreviews", _game.TrackPreviews);
_facts.Panel = _game.CurrentTool.ToString().ToLowerInvariant();
}
/// <summary>Testi del passo corrente, posizione del riquadro ed elemento evidenziato.</summary>
private void Refresh()
{
if (_machine is null) return;
bool show = _visible && _machine.Current is not null && !_game.ChronicleVisible && _game.Session.IsOpen;
_overlay.Visible = show;
if (!show) return;
var step = _machine.Current!;
if (_shownIndex != _machine.Index)
{
_shownIndex = _machine.Index;
_overlay.ShowStep(_machine.Index + 1, _machine.Script.Steps.Count, T(step.Title), T(step.Text), step.IsInformative, _machine.IsLast);
}
_overlay.Area = _game.TutorialArea();
Control? target = null;
if (step.Highlight is { } h) target = Shown(_game.TutorialTarget(h));
if (target is null && step.Fallback is { } f) target = Shown(_game.TutorialTarget(f));
_overlay.Target = target?.GetGlobalRect();
}
private static Control? Shown(Control? c) => c is not null && IsInstanceValid(c) && c.IsVisibleInTree() && c.Size.X > 0 ? c : null;
}
@@ -0,0 +1,178 @@
using Godot;
using RailEnterprise.Client.App;
using static RailEnterprise.Client.App.Localization;
namespace RailEnterprise.Client.Tutorial;
/// <summary>
/// Interfaccia del tutorial: riquadro ancorato in basso a sinistra dell'area della mappa (non modale, non
/// copre barra degli strumenti né pannello destro) e contorno ambra animato attorno all'elemento da
/// guardare. Tutto ciò che non è il riquadro lascia passare il mouse.
/// </summary>
public partial class TutorialOverlay : Control
{
private const float BoxWidth = 400;
private const float Margin = 16;
private readonly PanelContainer _box = new();
private readonly Label _counter = UiTheme.Text("", 12, Palette.TextSecondary);
private readonly Label _title = UiTheme.TitleLabel("", 26, Palette.AmberLight);
private readonly Label _text = UiTheme.Text("", 14);
private readonly Label _done = UiTheme.Text("", 13, Palette.Ok, bold: true);
private readonly ProgressBar _progress = new() { ShowPercentage = false, CustomMinimumSize = new Vector2(0, 4) };
private readonly VBoxContainer _body = new();
private readonly Button _next = UiTheme.Primary(T("Avanti"));
private readonly Button _skip = new() { Text = T("Salta passo") };
private readonly Button _close = new() { Text = T("Chiudi tutorial") };
private readonly Button _collapse = new() { Text = "–", Flat = true, CustomMinimumSize = new Vector2(28, 24) };
private readonly HighlightFrame _frame = new();
private double _doneTimer;
private bool _collapsed;
public event Action? NextPressed;
public event Action? SkipPressed;
public event Action? ClosePressed;
public override void _Ready()
{
SetAnchorsAndOffsetsPreset(LayoutPreset.FullRect);
MouseFilter = MouseFilterEnum.Ignore;
UiTheme.Apply(this);
AddChild(_frame);
_box.AddThemeStyleboxOverride("panel", UiTheme.Box(Palette.Panel, Palette.Amber, 10, 16));
_box.CustomMinimumSize = new Vector2(BoxWidth, 0);
AddChild(_box);
var col = new VBoxContainer();
col.AddThemeConstantOverride("separation", 8);
_box.AddChild(col);
var header = new HBoxContainer();
header.AddThemeConstantOverride("separation", 8);
header.AddChild(UiTheme.Badge(T("Tutorial")));
_counter.SizeFlagsHorizontal = SizeFlags.ExpandFill;
_counter.SizeFlagsVertical = SizeFlags.ShrinkCenter;
header.AddChild(_counter);
_collapse.TooltipText = T("Riduci o espandi il riquadro del tutorial");
_collapse.Pressed += () => SetCollapsed(!_collapsed);
header.AddChild(_collapse);
col.AddChild(header);
_progress.AddThemeStyleboxOverride("fill", UiTheme.Box(Palette.Amber, Palette.Amber, 2, 0));
_progress.AddThemeStyleboxOverride("background", UiTheme.Box(Palette.Border, Palette.Border, 2, 0));
col.AddChild(_progress);
_title.AutowrapMode = TextServer.AutowrapMode.WordSmart;
col.AddChild(_title);
_body.AddThemeConstantOverride("separation", 10);
col.AddChild(_body);
_text.AutowrapMode = TextServer.AutowrapMode.WordSmart;
_body.AddChild(_text);
_done.AutowrapMode = TextServer.AutowrapMode.WordSmart;
_done.Visible = false;
_body.AddChild(_done);
var buttons = new HBoxContainer();
buttons.AddThemeConstantOverride("separation", 8);
buttons.AddChild(_next);
buttons.AddChild(_skip);
buttons.AddChild(new Control { SizeFlagsHorizontal = SizeFlags.ExpandFill });
buttons.AddChild(_close);
_body.AddChild(buttons);
_next.Pressed += () => NextPressed?.Invoke();
_skip.Pressed += () => SkipPressed?.Invoke();
_close.Pressed += () => ClosePressed?.Invoke();
_close.TooltipText = T("Il tutorial si riapre con F1 o dal menu");
}
/// <summary>Mostra un passo: numero, titolo e testo già tradotti; Avanti solo per i passi informativi.</summary>
public void ShowStep(int number, int count, string title, string text, bool informative, bool last)
{
_counter.Text = string.Format(T("Passo {0} di {1}"), number, count);
_progress.MaxValue = count;
_progress.Value = number - 1;
_title.Text = title;
_text.Text = text;
_next.Visible = informative;
_next.Text = last ? T("Fine") : T("Avanti");
_skip.Visible = !informative;
}
/// <summary>Breve conferma del passo appena completato.</summary>
public void Flash(string completedTitle)
{
_done.Text = $"✓ {T("Fatto")}: {completedTitle}";
_done.Visible = true;
_doneTimer = 2.5;
}
/// <summary>Area libera in cui ancorare il riquadro (rettangolo globale della mappa o del pannello a tutto schermo).</summary>
public Rect2 Area { get; set; }
/// <summary>Elemento da evidenziare (rettangolo globale), null per nessuno.</summary>
public Rect2? Target
{
get => _frame.Target;
set => _frame.Target = value;
}
private void SetCollapsed(bool collapsed)
{
_collapsed = collapsed;
_body.Visible = !collapsed;
_collapse.Text = collapsed ? "+" : "–";
}
public override void _Process(double delta)
{
if (_doneTimer > 0)
{
_doneTimer -= delta;
if (_doneTimer <= 0) _done.Visible = false;
}
// in basso a sinistra dell'area libera; la larghezza si adatta alle finestre strette
var area = Area.Size == Vector2.Zero ? GetViewportRect() : Area;
float width = Math.Min(BoxWidth, Math.Max(240, area.Size.X - 2 * Margin));
_box.CustomMinimumSize = new Vector2(width, 0);
_box.Size = new Vector2(width, 0);
var size = _box.GetCombinedMinimumSize();
_box.Size = size;
_box.Position = new Vector2(area.Position.X + Margin, area.End.Y - Margin - size.Y);
}
/// <summary>Contorno ambra che pulsa attorno all'elemento evidenziato; non intercetta il mouse.</summary>
private sealed partial class HighlightFrame : Control
{
private double _time;
public Rect2? Target { get; set; }
public override void _Ready()
{
SetAnchorsAndOffsetsPreset(LayoutPreset.FullRect);
MouseFilter = MouseFilterEnum.Ignore;
}
public override void _Process(double delta)
{
_time += delta;
QueueRedraw();
}
public override void _Draw()
{
if (Target is not { } t || t.Size.X <= 0 || t.Size.Y <= 0) return;
float pulse = 0.5f + 0.5f * MathF.Sin((float)_time * 4f);
float grow = 3 + 3 * pulse;
var rect = t.Grow(grow);
rect.Position -= GetGlobalRect().Position;
var glow = new StyleBoxFlat { BgColor = Palette.WithAlpha(Palette.Amber, 0.06f + 0.06f * pulse), BorderColor = Palette.WithAlpha(Palette.AmberLight, 0.35f + 0.45f * pulse) };
glow.SetBorderWidthAll(3);
glow.SetCornerRadiusAll(10);
DrawStyleBox(glow, rect);
var outer = new StyleBoxFlat { BgColor = new Color(0, 0, 0, 0), BorderColor = Palette.WithAlpha(Palette.Amber, 0.25f * (1 - pulse)) };
outer.SetBorderWidthAll(2);
outer.SetCornerRadiusAll(14);
DrawStyleBox(outer, rect.Grow(6 + 4 * pulse));
}
}
}
@@ -0,0 +1,43 @@
using Godot;
namespace RailEnterprise.Client.Tutorial;
/// <summary>
/// Stato del tutorial nelle impostazioni del client (<c>user://settings.cfg</c>, sezione <c>tutorial</c>):
/// se il giocatore ha già aperto una partita (la casella «Mostra il tutorial» è attiva solo alla prima)
/// e l'avanzamento di ogni partita, con la chiave di <see cref="TutorialProgress.GameKey"/>.
/// </summary>
public static class TutorialSettings
{
private const string Path = "user://settings.cfg";
private const string Section = "tutorial";
/// <summary>Vero dopo la prima partita aperta.</summary>
public static bool Played
{
get => (bool)Load().GetValue(Section, "played", false);
set => Write(cfg => cfg.SetValue(Section, "played", value));
}
public static TutorialProgress? Read(string gameKey) =>
TutorialProgress.Decode((string)Load().GetValue(Section, gameKey, ""));
public static void Save(string gameKey, TutorialProgress progress) =>
Write(cfg => cfg.SetValue(Section, gameKey, progress.Encode()));
private static ConfigFile Load()
{
var cfg = new ConfigFile();
cfg.Load(Path);
return cfg;
}
private static void Write(Action<ConfigFile> change)
{
// si rilegge il file ogni volta: le altre impostazioni (lingua) restano com'erano
var cfg = Load();
change(cfg);
var error = cfg.Save(Path);
if (error != Error.Ok) GD.PushWarning($"Impostazioni del tutorial non salvate: {error}");
}
}
+1
View File
@@ -128,6 +128,7 @@ Requisito: stesso seme + stessi comandi agli stessi tick ⇒ stesso hash di stat
- `GameSession` applica i messaggi a `ClientWorld` (Protocol) sul thread principale; i comandi sono l'unico modo di cambiare il mondo; le anteprime del tracciato usano `TrackPreview` di Core.
- `MapView` (Node2D + Camera2D): `TerrainLayer` (texture per chunk con fasce, ombreggiatura, sponde e curve di livello; shader per le rive), `EntityLayer` (case, industrie, stazioni, depositi, alberi in MultiMesh), `TrackLayer` (massicciata, traversine, rotaie, opere, cantieri, segnali), `TrainLayer` (veicoli interpolati, fumo, avvisi), `ToolOverlay`; `LabelLayer` disegna le etichette in coordinate schermo.
- HUD: `TopBar`, `Toolbar`, pannello destro (pannelli degli strumenti e schede) con `Minimap`, `Ticker`. Pannelli: binari con profilo, stazione, deposito, treni, linee, officine (politica della flotta, avvisi, flotta per condizione, cartella di manutenzione, Registro officina, scorta di ricambi, mappa di calore), impieghi (Registro degli impieghi e convenzioni), mercato, finanze; a tutto schermo «Compagnie e borsa», «Mercato globale» (`MarketPanel`, immagine 06) e «La tua scalata» (`ClimbPanel`, immagine 08: binario dei livelli, storico del patrimonio con `SeriesChart` e i livelli segnati, requisiti, stato patrimoniale, conto economico, prestiti), che si apre anche dal livello nella `TopBar`; scheda dell'entità (con manutenzione del treno, lavoratori dell'industria, dove lavorano gli abitanti, avvisi degli eventi in corso). Sopra la minimappa il riquadro «Eventi in corso» (`WorldEventsBox`, testi in `WorldEventText`) elenca gli eventi del mondo del `DailyDigest`; il Mercato globale mostra quelli sulla domanda di un bene.
- Tutorial (ADR 0023): copione `assets/tutorial/tutorial.json`; logica pura senza Godot in `scripts/Tutorial/Logic` (`TutorialScript` con validazione, `TutorialFacts`, condizioni, `TutorialMachine`, `TutorialProgress`), compilata anche dal progetto dei test; `TutorialController` raccoglie i fatti osservati (entità della compagnia in `ClientWorld`, esiti riusciti dei comandi, strumento aperto, camera, velocità, anteprime del tracciato) e salva l'avanzamento per partita in `user://settings.cfg`; `TutorialOverlay` disegna il riquadro non modale e il contorno sull'elemento che `GameScreen.TutorialTarget` risolve. Si avvia dal menu («Mostra il tutorial», «Tutorial»), F1 lo nasconde o lo riapre; non c'è nel pilota automatico.
- Collaudo: pilota automatico (`-- --autopilot cartella`, `scripts/client-autopilot.sh`) con schermate.
## 10. Prestazioni
+8 -2
View File
@@ -141,11 +141,17 @@ Aggiornato alla fine di ogni fase (guida, sezione 18).
- client: pannello «Finanze» a tutto schermo (`FinancePanel`): conto economico con «Mesi» e «Anni», rating con misure e «per salire…», soglie e tassi, prestiti con rata, interessi, scadenza, «Rimborsa» ed «Estingui», richiesta con fido e tasso, barra dei giorni di cassa negativa solo con lo scoperto; frasi intere con segnaposto in `strings.csv`; schermata `18_finanze` nel pilota automatico (non provata qui: manca l'editor);
- IA invariate: usano gli stessi comandi di prestito; accettazione F5 (un'IA al livello 3 in 15 anni) e F4 (35 / 20 guasti senza la linea, 75 / 2 con la linea) invariate;
- test (`Economy/FinanceTests.cs`, 19, più il quadro via WebSocket in `ServerTests` e il round-trip di `FinanceReport`): tasso per rating e fisso, fido dal livello e rifiuti, interessi e quota capitale sul registro, rimborso parziale e totale, rating dalle due misure e leva infinita, spiegazione che porta al gradino sopra e rimborso possibile con la cassa, punteggio che basta già (senza infiniti), margine neutro ai primi incassi, finestra di 12 mesi, conto economico che somma all'utile, stipendi dei depositi, dazi, magazzini, dividendi incassati nell'utile, avvisi e bancarotta ai giorni di ogni preset (lento), rientro e oscillazioni senza notizie, quota dei trasporti senza dividendi, salvataggio versione 7 e migrazione dalla 6, determinismo con gli invarianti, proiezione. 194 test (175 senza i lenti).
- Restano della F6: ere e obsolescenza, pannello 07, tooltip «perché», tutorial, audio, bilanciamento con i bot.
- **Tutorial guidato della prima partita (issue #45, ADR 0023)**:
- copione nel client (`assets/tutorial/tutorial.json`, esportato con il gioco): 19 passi con chiavi di testo per `T()`, elemento da evidenziare con ripiego e condizione osservabile: benvenuto, mappa e zoom, velocità, due stazioni, deposito, strumento Binari, profilo e opere, costruzione, raccordo del deposito, cantieri finiti, locomotiva, carri, composizione, linea, assegnazione, Mercato globale, Finanze, La tua scalata, consigli;
- condizioni solo su ciò che il client riceve o fa: entità della compagnia in `ClientWorld`, esiti riusciti dei comandi (`cmd:<CommandType>`), pannello aperto, camera, velocità, anteprime del tracciato; nessun comando inviato, nessuna regola; logica pura senza Godot in `scripts/Tutorial/Logic` (copione con validazione, fatti, condizioni `counter`/`panel`/`all`/`any` con `atLeast`, `atMost`, `increase`, `TutorialMachine`, `TutorialProgress`);
- interfaccia: riquadro non modale in basso a sinistra della mappa (riducibile, non copre barra degli strumenti né pannello destro), contorno ambra animato sull'elemento, Avanti per i passi informativi, Salta passo, Chiudi tutorial, «Fatto: …» al completamento; F1 nasconde o riapre; menu con la casella «Mostra il tutorial» (attiva alla prima partita) e l'opzione «Tutorial» (partita locale dal primo passo);
- avanzamento per partita in `user://settings.cfg` (sezione `tutorial`, chiave da seme, impronta del terreno e compagnia del Welcome): si riprende dopo il caricamento, chiuso o completato resta nascosto; il pilota automatico non crea il tutorial (schermate invariate); Core, Protocol, Server e salvataggi invariati;
- testi italiani e inglesi in `strings.csv`; test (`Client/TutorialTests.cs`, 8, sulla logica collegata al progetto dei test): copione reale valido e completo, traduzioni presenti, pannelli allineati a `Hud.Tool` ed elementi risolti da `GameScreen`, condizioni con la base del passo, avanzamento, salta e chiudi, codifica e ripresa, piano di apertura, validazione dei copioni sbagliati, prima partita simulata che percorre tutto il copione. 202 test (183 senza i lenti); interfaccia non provata in Godot (qui manca l'editor).
- Restano della F6: ere e obsolescenza, pannello 07, tooltip «perché», audio, bilanciamento con i bot.
## Prossimo passo
- F6: ere e obsolescenza, pannello 07, tooltip «perché», tutorial, audio, bilanciamento con i bot su `simulate`.
- F6: ere e obsolescenza, pannello 07, tooltip «perché», audio, bilanciamento con i bot su `simulate`.
## Limiti noti
+66
View File
@@ -0,0 +1,66 @@
# ADR 0023 — Tutorial guidato della prima partita (F6)
Stato: accettato (F6, issue #45).
## Contesto
La guida (§16, F6) chiede un tutorial senza dire come farlo. Il client non contiene logica di gioco
(§14.3): un tutorial che controllasse le regole (per esempio «la stazione è nel posto giusto») le
duplicherebbe. Il formato dei salvataggi, il motore, il protocollo e il server non devono cambiare per una
funzione che riguarda solo l'esperienza del giocatore. Il pilota automatico del collaudo deve continuare a
produrre le stesse schermate.
## Decisione
1. **Copione come file dati del client.** I passi stanno in
`client/RailEnterprise.Client/assets/tutorial/tutorial.json` (esportato con il gioco: filtro
`assets/tutorial/*.json` nei preset), letto con il generatore di sorgente di System.Text.Json (campi
sconosciuti rifiutati, nessun pacchetto). Ogni passo ha `id`, chiavi `title` e `text` per `T()` (il
testo italiano, tradotto in `strings.csv` come il resto dell'interfaccia), l'elemento da evidenziare
(`highlight`) con un ripiego facoltativo (`fallback`, di solito il pulsante che apre il pannello) e la
condizione di completamento (`done`); senza condizione il passo è informativo e si chiude con Avanti.
2. **Condizioni osservabili, nessuna regola.** Una condizione è una sola forma tra: contatore
(`counter` con `atLeast`, `atMost` e/o `increase`), pannello aperto (`panel`), `all` e `any`.
`increase` confronta con il valore al primo aggiornamento del passo. I contatori vengono solo da ciò che
il client riceve o fa già: entità della compagnia nella copia locale `ClientWorld` (stazioni, depositi,
archi, archi in cantiere, locomotive, carri e carrozze, treni, linee, treni in linea, con il tipo dei
veicoli dai dati), esiti riusciti dei comandi (`CommandResultMessage`: `cmd:` + nome di `CommandType`),
spostamento della camera in schermate e zoom in logaritmi, cambi di velocità, anteprime del tracciato
mostrate; il pannello è lo strumento aperto nella barra (`Hud.Tool` in minuscolo). Il tutorial non invia
comandi e non decide se un'azione è buona: il server resta autorevole e i rifiuti arrivano come sempre.
3. **Logica pura separata.** `scripts/Tutorial/Logic` (copione, validazione, fatti, condizioni,
`TutorialMachine`, `TutorialProgress`) non dipende da Godot; il progetto dei test la compila per
collegamento e la prova (`tests/RailEnterprise.Tests/Client/TutorialTests.cs`). La parte Godot è
`TutorialController` (raccoglie i fatti ogni 0,2 s, fa avanzare la macchina, salva) e `TutorialOverlay`.
4. **Sequenza.** Benvenuto; muovi la mappa e lo zoom; velocità; due stazioni; deposito; strumento Binari;
profilo e opere (anteprima del tracciato, con ponti e gallerie nel riepilogo); costruisci; collega il
deposito; attendi i cantieri; locomotiva; carri; componi; linea; assegna; Mercato globale; Finanze; La
tua scalata; consigli. I conteggi delle entità sono assoluti (un tutorial ripreso non chiede di rifare
ciò che c'è già), i passi del binario contano i comandi riusciti dall'inizio del passo.
5. **Interfaccia.** Riquadro non modale ancorato in basso a sinistra dell'area della mappa (o del pannello
a tutto schermo, se aperto): non copre barra degli strumenti, barra superiore né pannello destro, si
riduce a una riga. Numero del passo, barra d'avanzamento, titolo, testo, «Fatto: …» per un istante,
pulsanti Avanti (solo informativi; «Fine» all'ultimo), Salta passo, Chiudi tutorial. Contorno ambra che
pulsa attorno all'elemento (pulsante della barra, velocità, livello, profilo, pulsanti dei pannelli
Treni e Linee, mappa). Colori e caratteri da `Palette`/`UiTheme` (immagine 05). Il riquadro si nasconde
con la Cronaca aperta e a connessione persa; F1 lo nasconde o lo riapre.
6. **Avvio e stato.** Nel menu la casella «Mostra il tutorial» è attiva finché non si è aperta una
partita (impostazione `tutorial/played`); «Tutorial» apre la partita locale con il tutorial dal primo
passo. L'avanzamento sta in `user://settings.cfg`, sezione `tutorial`, una voce per partita con chiave
`g_<seme>_<impronta del terreno>_<compagnia>` (dati del Welcome) e valore `active:<passo>`, `completed`
o `closed`. Aprendo una partita: un tutorial in corso si riprende dal passo salvato (anche dopo un
caricamento), uno chiuso o completato resta nascosto, senza voce si mostra solo se richiesto; la
richiesta del menu vale per la partita aperta, non per una Nuova partita+.
7. **Pilota automatico.** Con `--autopilot` il tutorial non si crea: le schermate del collaudo non cambiano.
## Conseguenze
- Nessun cambiamento a Core, Protocol, Server né al formato dei salvataggi. Nel client: punti d'aggancio
in `GameScreen` (`TutorialTarget`, `TutorialArea`, `CurrentTool`, `TrackPreviews`) e proprietà di sola
lettura su `Toolbar`, `TopBar`, `TrackPanel`, `TrainsPanel`, `LinesPanel`.
- Un nuovo passo si aggiunge nel JSON e in `strings.csv`; i test controllano copione, traduzioni, pannelli
allineati a `Hud.Tool` ed elementi risolti da `GameScreen`.
- Limiti: il tutorial non verifica che il deposito sia davvero raccordato (il passo dice di saltarlo se lo
è già); due partite con lo stesso seme, la stessa mappa e la stessa compagnia condividono la voce; i
pulsanti dei pannelli si evidenziano solo a pannello aperto (prima si evidenzia il pulsante della barra);
interfaccia non ancora provata in Godot (qui manca l'editor).
@@ -0,0 +1,284 @@
using System.Text;
using System.Text.RegularExpressions;
using RailEnterprise.Client.Tutorial;
using RailEnterprise.Core.Commands;
using RailEnterprise.Tests.Harness;
namespace RailEnterprise.Tests.Client;
/// <summary>Tutorial guidato del client (F6, issue #45, ADR 0023): copione, condizioni, macchina a stati, avanzamento salvato.</summary>
public static class TutorialTests
{
private static string ClientDir()
{
var dir = new DirectoryInfo(AppContext.BaseDirectory);
while (dir is not null)
{
string candidate = Path.Combine(dir.FullName, "client", "RailEnterprise.Client");
if (File.Exists(Path.Combine(candidate, "project.godot"))) return candidate;
dir = dir.Parent;
}
throw new DirectoryNotFoundException("Cartella del client non trovata");
}
private static TutorialScript RealScript() =>
TutorialScript.Parse(File.ReadAllText(Path.Combine(ClientDir(), "assets", "tutorial", "tutorial.json")));
private static TutorialStep Step(string id, TutorialCondition? done = null, string? highlight = null) =>
new() { Id = id, Title = "Titolo " + id, Text = "Testo " + id, Done = done, Highlight = highlight };
private static TutorialFacts Facts(string panel = TutorialFacts.NoPanel, params (string Counter, double Value)[] counters)
{
var f = new TutorialFacts { Panel = panel };
foreach (var (c, v) in counters) f.Set(c, v);
return f;
}
[Test(Description = "Il copione reale è valido e copre la sequenza minima della prima partita")]
public static void RealScriptIsValidAndComplete()
{
var script = RealScript();
var errors = script.Validate();
Assert.True(errors.Count == 0, string.Join("; ", errors));
string[] required =
[
"welcome", "map", "time", "stations", "depot", "track-tool", "track-profile", "track-build", "construction",
"locomotive", "cars", "compose", "line", "assign", "market", "finance", "climb", "tips",
];
int last = -1;
foreach (string id in required)
{
int i = script.IndexOf(id);
Assert.True(i > last, $"passo «{id}» mancante o fuori ordine");
last = i;
}
Assert.True(script.Steps[0].IsInformative, "si apre con un passo informativo");
Assert.True(script.Steps[^1].IsInformative, "si chiude con i consigli (informativo)");
// il profilo si guarda prima di costruire, e i pannelli finali si aprono davvero
Assert.Equal("track", script.Steps[script.IndexOf("track-tool")].Done!.Panel);
foreach (string panel in new[] { "market", "finance", "climb" })
Assert.Equal(panel, script.Steps[script.IndexOf(panel)].Done!.Panel);
}
[Test(Description = "Titoli, testi e scritte del tutorial hanno la riga in strings.csv con l'inglese")]
public static void TextsAreTranslated()
{
var rows = ReadCsv(Path.Combine(ClientDir(), "assets", "i18n", "strings.csv"));
var keys = new List<string>();
foreach (var s in RealScript().Steps) keys.AddRange([s.Title, s.Text]);
keys.AddRange(["Avanti", "Salta passo", "Chiudi tutorial", "Tutorial", "Passo {0} di {1}", "Fine", "Fatto", "Mostra il tutorial"]);
foreach (string key in keys)
{
Assert.True(rows.TryGetValue(key, out var row), $"manca in strings.csv: «{key}»");
Assert.True(row!.Length >= 3 && row[1].Length == 0 && row[2].Trim().Length > 0, $"riga senza inglese o con l'italiano non vuoto: «{key}»");
}
}
[Test(Description = "I pannelli noti al tutorial sono gli strumenti della barra (enum Tool del client)")]
public static void PanelsMatchToolbar()
{
string toolbar = File.ReadAllText(Path.Combine(ClientDir(), "scripts", "Hud", "Toolbar.cs"));
var m = Regex.Match(toolbar, @"public enum Tool\s*\{([^}]*)\}");
Assert.True(m.Success, "enum Tool non trovato");
var tools = m.Groups[1].Value.Split(',').Select(t => t.Trim().ToLowerInvariant()).Where(t => t.Length > 0).ToList();
Assert.SequenceEqual(tools, TutorialFacts.KnownPanels);
// e GameScreen risolve ogni elemento che non sia un pulsante della barra
string screen = File.ReadAllText(Path.Combine(ClientDir(), "scripts", "Screens", "GameScreen.cs"));
foreach (string target in TutorialScript.KnownTargets.Where(t => !t.StartsWith("toolbar:", StringComparison.Ordinal)))
Assert.True(screen.Contains($"\"{target}\" =>"), $"GameScreen.TutorialTarget non risolve «{target}»");
}
[Test(Description = "Contatori assoluti, aumenti dall'inizio del passo, pannello aperto, tutte e almeno una")]
public static void ConditionsUseFactsAndBaseline()
{
var empty = Facts();
var atLeast = new TutorialCondition { Counter = "stations", AtLeast = 2 };
Assert.False(atLeast.IsMet(Facts(counters: ("stations", 1)), empty));
Assert.True(atLeast.IsMet(Facts(counters: ("stations", 2)), empty));
var atMost = new TutorialCondition { Counter = "edgesBuilding", AtMost = 0 };
Assert.True(atMost.IsMet(empty, empty), "un contatore mai visto vale zero");
Assert.False(atMost.IsMet(Facts(counters: ("edgesBuilding", 1)), empty));
var increase = new TutorialCondition { Counter = "cmd:BuildTrack", Increase = 1 };
var baseline = Facts(counters: ("cmd:BuildTrack", 3));
Assert.False(increase.IsMet(Facts(counters: ("cmd:BuildTrack", 3)), baseline), "i binari costruiti prima del passo non contano");
Assert.True(increase.IsMet(Facts(counters: ("cmd:BuildTrack", 4)), baseline));
var panel = new TutorialCondition { Panel = "market" };
Assert.True(panel.IsMet(Facts("market"), empty));
Assert.False(panel.IsMet(Facts("finance"), empty));
var all = new TutorialCondition { All = [atLeast, panel] };
var any = new TutorialCondition { Any = [atLeast, panel] };
Assert.False(all.IsMet(Facts("market"), empty));
Assert.True(any.IsMet(Facts("market"), empty));
Assert.True(all.IsMet(Facts("market", ("stations", 2)), empty));
}
[Test(Description = "La macchina avanza sulle condizioni, Avanti sui passi informativi, Salta e Chiudi")]
public static void MachineAdvancesSkipsAndCloses()
{
var script = new TutorialScript
{
Steps =
[
Step("intro"),
Step("pan", new TutorialCondition { Counter = "mapPan", Increase = 0.5 }),
Step("stations", new TutorialCondition { Counter = "stations", AtLeast = 2 }),
Step("end"),
],
};
var m = new TutorialMachine(script);
Assert.Equal("intro", m.Current!.Id);
Assert.False(m.Update(Facts()), "un passo informativo non si completa da solo");
m.Next();
Assert.Equal("pan", m.Current!.Id);
// la base del passo è il primo aggiornamento: lo spostamento già fatto non conta
Assert.False(m.Update(Facts(counters: ("mapPan", 2))));
Assert.False(m.Update(Facts(counters: ("mapPan", 2.3))));
Assert.True(m.Update(Facts(counters: ("mapPan", 2.6))));
Assert.Equal("stations", m.Current!.Id);
Assert.Equal(new TutorialProgress("stations", TutorialStatus.Active), m.Progress);
m.Skip();
Assert.Equal("end", m.Current!.Id);
Assert.True(m.IsLast);
m.Next();
Assert.Equal(TutorialStatus.Completed, m.Status);
Assert.Equal(null, m.Current);
Assert.False(m.Update(Facts()));
m.Restart();
Assert.Equal("intro", m.Current!.Id);
m.Close();
Assert.Equal(TutorialStatus.Closed, m.Status);
Assert.Equal("closed", m.Progress.Encode());
m.Next();
Assert.Equal(TutorialStatus.Closed, m.Status, "chiuso, Avanti non fa nulla");
}
[Test(Description = "Avanzamento salvato: codifica, ripresa, passo sparito, piano di apertura")]
public static void ProgressRoundTripAndLaunchPlan()
{
foreach (var p in new[] { new TutorialProgress("depot", TutorialStatus.Active), new TutorialProgress(null, TutorialStatus.Completed), new TutorialProgress(null, TutorialStatus.Closed) })
Assert.Equal(p, TutorialProgress.Decode(p.Encode()));
Assert.Equal(null, TutorialProgress.Decode(""));
Assert.Equal(null, TutorialProgress.Decode("boh"));
var script = RealScript();
var m = new TutorialMachine(script);
m.Restore(new TutorialProgress("line", TutorialStatus.Active));
Assert.Equal("line", m.Current!.Id);
m.Restore(new TutorialProgress("passo-che-non-esiste-piu", TutorialStatus.Active));
Assert.Equal(script.Steps[0].Id, m.Current!.Id);
m.Restore(new TutorialProgress(null, TutorialStatus.Completed));
Assert.Equal(TutorialStatus.Completed, m.Status);
var active = new TutorialProgress("depot", TutorialStatus.Active);
var closed = new TutorialProgress(null, TutorialStatus.Closed);
Assert.Equal(TutorialLaunch.StartFresh, TutorialMachine.Plan(requested: true, restart: false, saved: null));
Assert.Equal(TutorialLaunch.Hidden, TutorialMachine.Plan(requested: false, restart: false, saved: null));
Assert.Equal(TutorialLaunch.Resume, TutorialMachine.Plan(requested: false, restart: false, saved: active));
Assert.Equal(TutorialLaunch.Hidden, TutorialMachine.Plan(requested: true, restart: false, saved: closed));
Assert.Equal(TutorialLaunch.StartFresh, TutorialMachine.Plan(requested: false, restart: true, saved: closed));
string key = TutorialProgress.GameKey(3, 0xABCDEFUL, 1);
Assert.Equal("g_0000000000000003_0000000000abcdef_1", key);
Assert.True(key.All(c => char.IsAsciiLetterOrDigit(c) || c == '_'), "chiave adatta a ConfigFile");
}
[Test(Description = "La validazione rifiuta copioni sbagliati e il parser i campi sconosciuti")]
public static void ValidationRejectsBadScripts()
{
static List<string> Errors(params TutorialStep[] steps) => new TutorialScript { Steps = [.. steps] }.Validate();
Assert.True(Errors(Step("a"), Step("a")).Exists(e => e.Contains("ripetuto")));
Assert.True(Errors(Step("a", new TutorialCondition { Counter = "binari", AtLeast = 1 })).Exists(e => e.Contains("contatore sconosciuto")));
Assert.True(Errors(Step("a", new TutorialCondition { Counter = "cmd:Teletrasporto", Increase = 1 })).Exists(e => e.Contains("contatore sconosciuto")));
Assert.True(Errors(Step("a", new TutorialCondition { Counter = "cmd:5", Increase = 1 })).Exists(e => e.Contains("contatore sconosciuto")));
Assert.True(Errors(Step("a", new TutorialCondition { Counter = "stations" })).Exists(e => e.Contains("senza atLeast")));
Assert.True(Errors(Step("a", new TutorialCondition { Panel = "cucina" })).Exists(e => e.Contains("pannello sconosciuto")));
Assert.True(Errors(Step("a", new TutorialCondition { Panel = "market", Counter = "stations", AtLeast = 1 })).Exists(e => e.Contains("una sola forma")));
Assert.True(Errors(Step("a", new TutorialCondition { All = [] })).Exists(e => e.Contains("vuoto")));
Assert.True(Errors(Step("a", highlight: "toolbar:cucina")).Exists(e => e.Contains("evidenziare sconosciuto")));
Assert.True(Errors().Exists(e => e.Contains("nessun passo")));
Assert.Equal(0, Errors(Step("a", new TutorialCondition { Counter = TutorialFacts.CommandCounter(CommandType.BuildStation), Increase = 1 }, "toolbar:station")).Count);
Assert.Throws<System.Text.Json.JsonException>(() => TutorialScript.Parse("""{ "steps": [ { "id": "a", "title": "t", "text": "x", "colore": "rosso" } ] }"""));
Assert.Throws<System.Text.Json.JsonException>(() => TutorialScript.Parse("""{ "steps": [ { "id": "a", "text": "x" } ] }"""));
}
[Test(Description = "Una prima partita simulata con fatti plausibili percorre tutto il copione reale")]
public static void FirstGameWalksTheWholeScript()
{
var script = RealScript();
var m = new TutorialMachine(script);
var f = new TutorialFacts();
int guard = 0;
void Tick() => m.Update(f);
while (m.Status == TutorialStatus.Active && guard++ < 200)
{
var step = m.Current!;
Tick();
if (step.IsInformative)
{
m.Next();
continue;
}
// il giocatore fa ciò che il passo chiede; il client osserva soltanto gli effetti
switch (step.Id)
{
case "map": f.Add("mapPan", 0.8); f.Add("mapZoom", 0.6); break;
case "time": f.Add("speedChanges", 1); break;
case "stations": f.Add(TutorialFacts.CommandCounter(CommandType.BuildStation), 2); f.Set("stations", 2); break;
case "depot": f.Set("depots", 1); break;
case "track-tool": f.Panel = "track"; break;
case "track-profile": f.Add("trackPreviews", 12); break;
case "track-build" or "depot-link": f.Add(TutorialFacts.CommandCounter(CommandType.BuildTrack), 1); f.Add("edges", 1); f.Add("edgesBuilding", 1); break;
case "construction": f.Set("edgesBuilding", 0); f.Set("edgesActive", f.Get("edges")); break;
case "locomotive": f.Panel = "trains"; f.Set("locomotives", 1); break;
case "cars": f.Set("cars", 3); break;
case "compose": f.Set("trains", 1); break;
case "line": f.Panel = "lines"; f.Set("lines", 1); break;
case "assign": f.Panel = "trains"; f.Set("trainsOnLine", 1); break;
default: f.Panel = step.Done!.Panel ?? f.Panel; break;
}
int before = m.Index;
Tick();
Assert.True(m.Index == before + 1 || m.Status != TutorialStatus.Active, $"il passo «{step.Id}» non si è completato");
}
Assert.Equal(TutorialStatus.Completed, m.Status);
}
/// <summary>CSV minimo (virgolette doppie, virgole tra virgolette), come lo legge Godot.</summary>
private static Dictionary<string, string[]> ReadCsv(string path)
{
var rows = new Dictionary<string, string[]>(StringComparer.Ordinal);
foreach (string line in File.ReadAllLines(path, Encoding.UTF8).Skip(1))
{
if (line.Length == 0) continue;
var fields = new List<string>();
var sb = new StringBuilder();
bool quoted = false;
for (int i = 0; i < line.Length; i++)
{
char c = line[i];
if (quoted)
{
if (c == '"' && i + 1 < line.Length && line[i + 1] == '"') { sb.Append('"'); i++; }
else if (c == '"') quoted = false;
else sb.Append(c);
}
else if (c == '"') quoted = true;
else if (c == ',') { fields.Add(sb.ToString()); sb.Clear(); }
else sb.Append(c);
}
fields.Add(sb.ToString());
rows[fields[0]] = [.. fields];
}
return rows;
}
}
@@ -13,6 +13,11 @@
<ProjectReference Include="..\..\src\RailEnterprise.Server\RailEnterprise.Server.csproj" />
</ItemGroup>
<!-- Logica pura del tutorial del client (senza Godot, ADR 0023): compilata anche qui per provarla. -->
<ItemGroup>
<Compile Include="..\..\client\RailEnterprise.Client\scripts\Tutorial\Logic\*.cs" LinkBase="ClientTutorial" />
</ItemGroup>
<ItemGroup>
<Content Include="..\..\data\**\*.json" LinkBase="data" CopyToOutputDirectory="PreserveNewest" />
<Content Include="scenarios\**\*.json" CopyToOutputDirectory="PreserveNewest" />