F6: tutorial, correzioni della revisione
CI / Build e test (pull_request) Successful in 1m29s
CI / Immagine Docker (pull_request) Successful in 30s

Unisce origin/main (audio, ere e obsolescenza, scheda dell'industria e
schermata di connessione) e corregge i rilievi della revisione del
tutorial (ADR 0023 aggiornato).

- Chiave dell'avanzamento senza l'impronta del terreno, che il server
  ricalcola e che cambia giocando (città, industrie): origine della
  partita, seme, lato, anno d'inizio, regione e compagnia. Un tutorial
  ripreso dopo un anno di gioco ritrova la sua voce.
- «Tutorial» apre una partita locale di prova sempre nuova in
  user://tutorial-server invece di riprendere l'autosalvataggio del
  giocatore e rifare il tutorial lì dentro; con salvataggi locali già
  presenti la casella «Mostra il tutorial» parte spenta. Casella e
  pulsante passano nella nuova ConnectScreen (MenuScreen non c'è più).
- La casella spuntata vale anche su una voce chiusa o completata (stesso
  seme di una partita vecchia).
- Contorno ritagliato dai contenitori a scorrimento, con l'elemento
  portato in vista; del tutto nascosto si usa il ripiego.
- Pulsanti del riquadro senza fuoco: Invio e spazio restano alla
  partita (Costruisci, pausa) e non saltano il passo.
- La base di «increase» è presa al completamento del passo precedente e
  gli esiti dei comandi si valutano subito: un binario costruito appena
  dopo conta per il passo nuovo.
- Velocità contata solo dalle richieste di questo client.
- Copione mancante o non valido segnalato nella partita; validazione
  dei null ammessi dal JSON.
- Test: chiave stabile con impronta diversa, base al completamento,
  piano con la casella, null nel copione. 228 test (208 senza i lenti).

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:51:31 +01:00
commit 64209afd5f
75 files changed
+7612 -571

No files matched your search

@@ -11,9 +11,9 @@ 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.
/// copia locale, esiti dei comandi, pannello aperto, camera, velocità chiesta da questo client, 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
{
@@ -21,6 +21,7 @@ public partial class TutorialController : Node
private const double FactsInterval = 0.2;
private readonly GameScreen _game;
private readonly string _scope;
private bool _requested;
private bool _restart;
private readonly CanvasLayer _layer = new() { Layer = 3 };
@@ -28,19 +29,24 @@ public partial class TutorialController : Node
private readonly TutorialFacts _facts = new();
private readonly Dictionary<string, VehicleKind> _vehicleKinds = [];
private TutorialMachine? _machine;
private string? _loadError;
private string _gameKey = "";
private bool _visible;
private int _shownIndex = -1;
// controllo già portato in vista nel suo contenitore a scorrimento per il passo mostrato
private Control? _scrolledTo;
private double _sinceFacts = FactsInterval;
private Vector2? _lastCamera;
private float _lastZoom;
private byte? _lastSpeed;
private int _lastSpeedRequests;
/// <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)
/// <param name="scope">origine della partita (locale, tutorial, server remoto) per la chiave dell'avanzamento</param>
/// <param name="requested">casella «Mostra il tutorial» della schermata di connessione</param>
/// <param name="restart">pulsante «Tutorial» della schermata di connessione: dal primo passo anche se già fatto</param>
public TutorialController(GameScreen game, string scope, bool requested, bool restart)
{
_game = game;
_scope = scope;
_requested = requested;
_restart = restart;
}
@@ -58,7 +64,10 @@ public partial class TutorialController : Node
}
catch (Exception e)
{
_loadError = e.Message;
GD.PushWarning($"Tutorial non disponibile: {e.Message}");
// chi l'ha chiesto deve saperlo: altrimenti vedrebbe una partita normale senza spiegazioni
if (_requested || _restart) ReportUnavailable();
return;
}
foreach (var v in _game.Session.World.Data.Vehicles) _vehicleKinds[v.Id] = v.Kind;
@@ -68,16 +77,19 @@ public partial class TutorialController : Node
_overlay.SkipPressed += () => Act(m => m.Skip());
_overlay.ClosePressed += () => Act(m => m.Close());
_game.Session.MessageApplied += OnMessage;
_lastSpeedRequests = _game.Session.SpeedRequests;
OpenForGame();
}
public override void _ExitTree() => _game.Session.MessageApplied -= OnMessage;
private void ReportUnavailable() => _game.Toast(string.Format(T("Tutorial non disponibile: {0}"), _loadError), error: true);
/// <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);
_gameKey = TutorialProgress.GameKey(_scope, s);
var saved = TutorialSettings.Read(_gameKey);
switch (TutorialMachine.Plan(_requested, _restart, saved))
{
@@ -96,10 +108,9 @@ public partial class TutorialController : Node
_visible = false;
break;
}
// casella e opzione del menu valgono per la partita aperta, non per le successive (Nuova partita+)
// casella e pulsante della schermata di connessione valgono per la partita aperta, non per le successive (Nuova partita+)
_requested = _restart = false;
_lastCamera = null;
_lastSpeed = null;
_shownIndex = -1;
Refresh();
}
@@ -113,6 +124,8 @@ public partial class TutorialController : Node
break;
case CommandResultMessage { Ok: true } r:
_facts.Add(TutorialFacts.CommandCounter((CommandType)r.Type), 1);
// subito, non al prossimo giro: due esiti ravvicinati contano per due passi diversi
Evaluate();
break;
}
}
@@ -133,7 +146,12 @@ public partial class TutorialController : Node
public override void _UnhandledKeyInput(InputEvent e)
{
if (_machine is null || e is not InputEventKey { Pressed: true, Echo: false, Keycode: Key.F1 }) return;
if (e is not InputEventKey { Pressed: true, Echo: false, Keycode: Key.F1 }) return;
if (_machine is null)
{
if (_loadError is not null) ReportUnavailable();
return;
}
if (_visible)
{
// F1 nasconde soltanto: il tutorial in corso resta salvato
@@ -160,22 +178,24 @@ public partial class TutorialController : Node
{
_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;
}
}
Evaluate();
}
Refresh();
}
/// <summary>Spostamento della camera (in schermate), zoom (in logaritmi) e cambi di velocità, sommati.</summary>
/// <summary>Valuta il passo corrente sui fatti raccolti; se si completa salva e mostra «Fatto».</summary>
private void Evaluate()
{
if (_machine is null || !_visible) return;
string? title = _machine.Current is { } step ? T(step.Title) : null;
if (!_machine.Update(_facts)) return;
Save();
if (title is not null) _overlay.Flash(title);
// completato l'ultimo passo il riquadro si chiude
if (_machine.Status != TutorialStatus.Active) _visible = false;
}
/// <summary>Spostamento della camera (in schermate), zoom (in logaritmi) e velocità chieste da questo client, sommati.</summary>
private void TrackCameraAndSpeed()
{
var map = _game.Map;
@@ -197,10 +217,10 @@ public partial class TutorialController : Node
_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;
// solo le richieste di questo client: un altro giocatore che cambia la velocità del server non conta
int requests = _game.Session.SpeedRequests;
if (requests != _lastSpeedRequests) _facts.Add("speedChanges", requests - _lastSpeedRequests);
_lastSpeedRequests = requests;
}
/// <summary>Entità della compagnia nella copia locale, pannello aperto, anteprime del tracciato.</summary>
@@ -253,14 +273,40 @@ public partial class TutorialController : Node
if (_shownIndex != _machine.Index)
{
_shownIndex = _machine.Index;
_scrolledTo = null;
_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();
Rect2? target = null;
if (step.Highlight is { } h) target = VisibleRect(_game.TutorialTarget(h));
if (target is null && step.Fallback is { } f) target = VisibleRect(_game.TutorialTarget(f));
_overlay.Target = target;
}
private static Control? Shown(Control? c) => c is not null && IsInstanceValid(c) && c.IsVisibleInTree() && c.Size.X > 0 ? c : null;
/// <summary>
/// Rettangolo visibile di un controllo, ritagliato dai contenitori a scorrimento che lo contengono (barra
/// degli strumenti, pannello destro); null se il controllo non c'è o è del tutto fuori vista, così si usa
/// il ripiego e il contorno non finisce su ciò che sta sotto. La prima volta in un passo il controllo
/// coperto dallo scorrimento si porta in vista.
/// </summary>
private Rect2? VisibleRect(Control? c)
{
if (c is null || !IsInstanceValid(c) || !c.IsVisibleInTree() || c.Size.X <= 0) return null;
if (_scrolledTo != c)
{
_scrolledTo = c;
for (var p = c.GetParent(); p is not null; p = p.GetParent())
{
if (p is ScrollContainer scroll) scroll.EnsureControlVisible(c);
}
}
var rect = c.GetGlobalRect();
for (var p = c.GetParent(); p is not null; p = p.GetParent())
{
if (p is not ScrollContainer scroll) continue;
rect = rect.Intersection(scroll.GetGlobalRect());
if (rect.Size.X < 1 || rect.Size.Y < 1) return null;
}
return rect;
}
}