Tutorial facoltativo che accompagna il giocatore dalla mappa alla prima linea in servizio e poi a Mercato globale, Finanze e La tua scalata. È un'esperienza del solo client: osserva ciò che il client già riceve (entità della compagnia in ClientWorld, esiti riusciti dei comandi, pannello aperto, camera, velocità, anteprime del tracciato), non invia comandi e non decide regole; Core, Protocol, Server e salvataggi non cambiano (ADR 0023). - Copione in assets/tutorial/tutorial.json (19 passi, chiavi di testo per T(), elemento da evidenziare con ripiego, condizione osservabile), esportato con il gioco; testi italiani e inglesi in strings.csv. - Logica pura senza Godot in scripts/Tutorial/Logic: copione con validazione, fatti, condizioni counter/panel/all/any, macchina a stati, avanzamento salvato; compilata anche dal progetto dei test (8 test). - Riquadro non modale in basso a sinistra della mappa, contorno ambra animato, Avanti / Salta passo / Chiudi tutorial, F1 per nasconderlo o riaprirlo; nel menu la casella «Mostra il tutorial» (attiva alla prima partita) e l'opzione «Tutorial». - Avanzamento per partita in user://settings.cfg, ripreso dopo il caricamento; il pilota automatico non crea il tutorial. Refs #45. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
160 lines
6.0 KiB
C#
160 lines
6.0 KiB
C#
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: 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.
|
|
/// </summary>
|
|
public static string GameKey(ulong seed, ulong terrainHash, int companyId) => $"g_{seed:x16}_{terrainHash:x16}_{companyId}";
|
|
|
|
/// <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 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"/> (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).
|
|
/// </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;
|
|
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();
|
|
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 dal menu.</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;
|
|
}
|
|
}
|