Files
Rail_Enterprise/client/RailEnterprise.Client/scripts/Tutorial/Logic/TutorialMachine.cs
T
Alby96andClaude Opus 5.5 ebe4308e75 F6: tutorial guidato della prima partita
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>
2026-11-08 14:21:12 +01:00

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:&lt;id&gt;</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;
}
}