using RailEnterprise.Protocol.Messages;
namespace RailEnterprise.Client.Tutorial;
/// Stato del tutorial di una partita.
public enum TutorialStatus
{
/// In corso su un passo.
Active,
/// Tutti i passi completati o saltati.
Completed,
/// Chiuso dal giocatore prima della fine.
Closed,
}
/// Cosa fare all'apertura di una partita (vedi ).
public enum TutorialLaunch
{
/// Nessun tutorial.
Hidden,
/// Dal primo passo.
StartFresh,
/// Dal passo salvato.
Resume,
}
///
/// Avanzamento salvato nelle impostazioni del client (una voce per partita): passo corrente e stato.
/// Il testo è active:<id>, completed o closed.
///
public readonly record struct TutorialProgress(string? StepId, TutorialStatus Status)
{
public string Encode() => Status switch
{
TutorialStatus.Active => "active:" + (StepId ?? ""),
TutorialStatus.Completed => "completed",
_ => "closed",
};
///
/// Chiave della partita nelle impostazioni: origine (: 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.
///
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}");
/// Chiave della partita dal riepilogo del Welcome (vedi l'altra forma).
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]) : '_';
});
/// Legge una voce salvata; null se vuota o non riconosciuta.
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;
}
}
///
/// Macchina a stati dei passi: un passo alla volta, completato quando la sua condizione è vera sui fatti
/// osservati (), oppure con Avanti (passi informativi), Salta passo o Chiudi. I contatori
/// con increase 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.
///
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; }
/// Indice del passo corrente (uguale al numero di passi a tutorial completato).
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;
/// Avanzamento da salvare.
public TutorialProgress Progress => new(Current?.Id, Status);
///
/// Decide se mostrare il tutorial all'apertura di una partita. (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.
///
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;
}
/// Riparte dal primo passo.
public void Restart() => GoTo(0);
/// Riprende da un avanzamento salvato; un passo che non c'è più fa ripartire dall'inizio.
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;
}
}
/// Valuta il passo corrente sui fatti; se la condizione è vera passa al successivo e restituisce true.
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;
}
/// Avanti: chiude un passo informativo (sugli altri equivale a ).
public void Next() => Advance();
/// Salta il passo corrente.
public void Skip() => Advance();
/// Chiude il tutorial; si potrà riaprire con F1 o dalla schermata iniziale.
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;
}
}