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; } }