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

@@ -1,3 +1,5 @@
using RailEnterprise.Protocol.Messages;
namespace RailEnterprise.Client.Tutorial;
/// <summary>Stato del tutorial di una partita.</summary>
@@ -36,10 +38,23 @@ public readonly record struct TutorialProgress(string? StepId, TutorialStatus St
};
/// <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.
/// Chiave della partita nelle impostazioni: origine (<paramref name="scope"/>: partita locale, partita di
/// prova del tutorial, server remoto) e i dati del Welcome che non cambiano durante una partita (seme,
/// lato della mappa, anno d'inizio, regione, compagnia del giocatore). Non usa l'impronta del terreno né
/// la data: cambiano giocando (città che crescono, industrie che aprono e chiudono), e la stessa partita
/// ricaricata non ritroverebbe la sua voce. Solo lettere minuscole, cifre e trattini bassi.
/// </summary>
public static string GameKey(ulong seed, ulong terrainHash, int companyId) => $"g_{seed:x16}_{terrainHash:x16}_{companyId}";
public static string GameKey(string scope, ulong seed, int sizeKm, int startYear, string regionId, int companyId) =>
Clean($"g_{scope}_{seed:x16}_{sizeKm}_{startYear}_{regionId}_{companyId}");
/// <summary>Chiave della partita dal riepilogo del Welcome (vedi l'altra forma).</summary>
public static string GameKey(string scope, WorldSummary s) => GameKey(scope, s.Seed, s.SizeKm, s.StartYear, s.RegionId, s.CompanyId);
private static string Clean(string text) =>
string.Create(text.Length, text, (span, t) =>
{
for (int i = 0; i < t.Length; i++) span[i] = char.IsAsciiLetterOrDigit(t[i]) ? char.ToLowerInvariant(t[i]) : '_';
});
/// <summary>Legge una voce salvata; null se vuota o non riconosciuta.</summary>
public static TutorialProgress? Decode(string? text)
@@ -60,8 +75,10 @@ public readonly record struct TutorialProgress(string? StepId, TutorialStatus St
/// <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.
/// con <c>increase</c> si confrontano con i fatti di quando il passo precedente si è completato da sé (così
/// un'azione arrivata subito dopo conta per il passo nuovo), oppure, dopo Avanti, Salta, una ripresa o una
/// ripartenza, 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
{
@@ -88,15 +105,17 @@ public sealed class TutorialMachine
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).
/// Decide se mostrare il tutorial all'apertura di una partita. <paramref name="restart"/> (pulsante «Tutorial»
/// della schermata di connessione) riparte sempre dal primo passo; un tutorial in corso in quella partita si riprende; uno
/// completato o chiuso resta nascosto, a meno che il giocatore l'abbia chiesto con la casella «Mostra il
/// tutorial» (attiva da sé solo alla prima partita: spuntarla dopo è una richiesta esplicita, e una
/// partita nuova con lo stesso seme ha la stessa chiave di una vecchia); senza voce salvata si mostra solo
/// se chiesto.
/// </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;
if (saved is { Status: TutorialStatus.Active }) return TutorialLaunch.Resume;
return requested ? TutorialLaunch.StartFresh : TutorialLaunch.Hidden;
}
@@ -128,6 +147,9 @@ public sealed class TutorialMachine
_baseline ??= facts.Clone();
if (step.Done is null || !step.Done.IsMet(facts, _baseline)) return false;
Advance();
// la base del passo nuovo sono i fatti di adesso, non quelli del suo primo aggiornamento: un comando
// riuscito arrivato prima di quell'aggiornamento conta per il passo nuovo
if (Status == TutorialStatus.Active) _baseline = facts.Clone();
return true;
}
@@ -137,7 +159,7 @@ public sealed class TutorialMachine
/// <summary>Salta il passo corrente.</summary>
public void Skip() => Advance();
/// <summary>Chiude il tutorial; si potrà riaprire dal menu.</summary>
/// <summary>Chiude il tutorial; si potrà riaprire con F1 o dalla schermata iniziale.</summary>
public void Close()
{
if (Status == TutorialStatus.Active) Status = TutorialStatus.Closed;