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>
182 lines
7.6 KiB
C#
182 lines
7.6 KiB
C#
using RailEnterprise.Protocol.Messages;
|
|
|
|
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:<id></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: 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(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)
|
|
{
|
|
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 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
|
|
{
|
|
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"/> (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 { Status: TutorialStatus.Active }) return TutorialLaunch.Resume;
|
|
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();
|
|
// 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;
|
|
}
|
|
|
|
/// <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 con F1 o dalla schermata iniziale.</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;
|
|
}
|
|
}
|