Files
Rail_Enterprise/client/RailEnterprise.Client/scripts/Tutorial/Logic/TutorialScript.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

206 lines
10 KiB
C#

using System.Text.Json;
using System.Text.Json.Serialization;
using RailEnterprise.Core.Commands;
namespace RailEnterprise.Client.Tutorial;
/// <summary>
/// Copione del tutorial guidato (<c>assets/tutorial/tutorial.json</c>, ADR 0023): l'elenco ordinato dei
/// passi. È un file dati del client, non del motore: non cambia regole né salvataggi. Questa classe e le
/// altre di <c>Tutorial/Logic</c> non dipendono da Godot e si provano nel harness dei test.
/// </summary>
public sealed class TutorialScript
{
/// <summary>Versione del formato del file (oggi 1).</summary>
public int Version { get; init; } = 1;
public List<TutorialStep> Steps { get; init; } = [];
/// <summary>Indice del passo con l'id indicato, -1 se non c'è.</summary>
public int IndexOf(string? id) => id is null ? -1 : Steps.FindIndex(s => s.Id == id);
/// <summary>Legge il copione dal testo JSON (commenti e virgole finali ammessi, campi sconosciuti rifiutati).</summary>
public static TutorialScript Parse(string json) =>
JsonSerializer.Deserialize(json, TutorialJsonContext.Default.TutorialScript)
?? throw new JsonException("Copione del tutorial vuoto");
/// <summary>
/// Elementi dell'interfaccia che un passo può evidenziare. Il client li risolve nei controlli
/// (<c>GameScreen.TutorialTarget</c>); se un elemento non è visibile in quel momento si usa il
/// ripiego del passo, altrimenti non si evidenzia nulla.
/// </summary>
public static readonly IReadOnlyList<string> KnownTargets = BuildTargets();
private static List<string> BuildTargets()
{
var list = new List<string> { "map", "side", "full", "topbar:speed", "topbar:tier", "track:profile", "track:build", "trains:buy", "trains:compose", "trains:assign", "lines:create" };
foreach (string panel in TutorialFacts.KnownPanels)
{
if (panel != TutorialFacts.NoPanel) list.Add("toolbar:" + panel);
}
return list;
}
/// <summary>Controlla il copione: id unici, testi presenti, elementi, contatori e pannelli noti. Restituisce gli errori in italiano.</summary>
public List<string> Validate()
{
var errors = new List<string>();
if (Version != 1) errors.Add($"versione {Version} non supportata");
if (Steps.Count == 0) errors.Add("nessun passo");
var ids = new HashSet<string>(StringComparer.Ordinal);
foreach (var step in Steps)
{
string where = $"passo «{step.Id}»";
if (string.IsNullOrWhiteSpace(step.Id)) errors.Add("passo senza id");
else if (!ids.Add(step.Id)) errors.Add($"{where}: id ripetuto");
if (string.IsNullOrWhiteSpace(step.Title)) errors.Add($"{where}: titolo vuoto");
if (string.IsNullOrWhiteSpace(step.Text)) errors.Add($"{where}: testo vuoto");
if (step.Highlight is { } h && !KnownTargets.Contains(h)) errors.Add($"{where}: elemento da evidenziare sconosciuto «{h}»");
if (step.Fallback is { } f && !KnownTargets.Contains(f)) errors.Add($"{where}: ripiego sconosciuto «{f}»");
if (step.Fallback is not null && step.Highlight is null) errors.Add($"{where}: ripiego senza elemento principale");
step.Done?.Validate(where, errors);
}
return errors;
}
}
/// <summary>Passo del tutorial: testi (chiavi di traduzione), elemento da evidenziare, condizione di completamento.</summary>
public sealed class TutorialStep
{
public required string Id { get; init; }
/// <summary>Chiave del titolo per <c>T()</c> (testo italiano).</summary>
public required string Title { get; init; }
/// <summary>Chiave del testo per <c>T()</c> (testo italiano).</summary>
public required string Text { get; init; }
/// <summary>Elemento dell'interfaccia da evidenziare (vedi <see cref="TutorialScript.KnownTargets"/>), facoltativo.</summary>
public string? Highlight { get; init; }
/// <summary>Elemento da evidenziare quando il principale non è visibile (per esempio il pulsante che apre il pannello).</summary>
public string? Fallback { get; init; }
/// <summary>Condizione osservabile che completa il passo; senza condizione il passo è informativo (pulsante Avanti).</summary>
public TutorialCondition? Done { get; init; }
[JsonIgnore]
public bool IsInformative => Done is null;
}
/// <summary>
/// Condizione di completamento, valutata su fatti semplici che il client osserva (<see cref="TutorialFacts"/>).
/// Ha una sola forma tra: contatore (<c>counter</c> con <c>atLeast</c>, <c>atMost</c> e/o <c>increase</c>),
/// pannello aperto (<c>panel</c>), tutte (<c>all</c>) o almeno una (<c>any</c>) di altre condizioni.
/// <c>increase</c> confronta il contatore con il suo valore all'inizio del passo.
/// </summary>
public sealed class TutorialCondition
{
public string? Counter { get; init; }
public double? AtLeast { get; init; }
public double? AtMost { get; init; }
public double? Increase { get; init; }
public string? Panel { get; init; }
public List<TutorialCondition>? All { get; init; }
public List<TutorialCondition>? Any { get; init; }
/// <summary>Vera se i fatti di adesso soddisfano la condizione; <paramref name="baseline"/> sono i fatti all'inizio del passo.</summary>
public bool IsMet(TutorialFacts now, TutorialFacts baseline)
{
if (All is not null) return All.TrueForAll(c => c.IsMet(now, baseline));
if (Any is not null) return Any.Exists(c => c.IsMet(now, baseline));
if (Panel is not null) return now.Panel == Panel;
if (Counter is null) return false;
double value = now.Get(Counter);
if (AtLeast is { } min && value < min) return false;
if (AtMost is { } max && value > max) return false;
if (Increase is { } inc && value - baseline.Get(Counter) < inc) return false;
return true;
}
internal void Validate(string where, List<string> errors)
{
int forms = (Counter is not null ? 1 : 0) + (Panel is not null ? 1 : 0) + (All is not null ? 1 : 0) + (Any is not null ? 1 : 0);
if (forms != 1)
{
errors.Add($"{where}: la condizione deve avere una sola forma tra counter, panel, all e any");
return;
}
if (Counter is not null)
{
if (AtLeast is null && AtMost is null && Increase is null) errors.Add($"{where}: contatore «{Counter}» senza atLeast, atMost o increase");
if (!TutorialFacts.IsKnownCounter(Counter)) errors.Add($"{where}: contatore sconosciuto «{Counter}»");
}
else if (AtLeast is not null || AtMost is not null || Increase is not null)
{
errors.Add($"{where}: atLeast, atMost e increase valgono solo con counter");
}
if (Panel is not null && !TutorialFacts.KnownPanels.Contains(Panel)) errors.Add($"{where}: pannello sconosciuto «{Panel}»");
foreach (var list in new[] { All, Any })
{
if (list is null) continue;
if (list.Count == 0) errors.Add($"{where}: elenco di condizioni vuoto");
foreach (var c in list) c.Validate(where, errors);
}
}
}
/// <summary>Fatti osservati dal client: contatori (entità della compagnia, comandi riusciti, azioni sulla mappa) e pannello aperto.</summary>
public sealed class TutorialFacts
{
/// <summary>Pannello «nessuno» (barra degli strumenti senza selezione).</summary>
public const string NoPanel = "none";
/// <summary>Prefisso dei contatori dei comandi riusciti: <c>cmd:</c> + nome di <see cref="CommandType"/>.</summary>
public const string CommandPrefix = "cmd:";
/// <summary>Pannelli della barra degli strumenti, con i nomi in minuscolo dell'enumerazione <c>Hud.Tool</c>.</summary>
public static readonly IReadOnlyList<string> KnownPanels =
[
NoPanel, "track", "station", "signal", "depot", "trains", "lines", "maintenance", "employment", "industries", "market", "companies", "climb", "finance", "demolish",
];
/// <summary>
/// Contatori osservati: entità della compagnia nella copia locale (stazioni, depositi, archi, archi in
/// funzione, archi in cantiere, locomotive, carri e carrozze, treni, linee, treni in linea), azioni del
/// giocatore sulla mappa (spostamento in schermate, zoom in unità logaritmiche, cambi di velocità) e
/// anteprime valide del tracciato.
/// </summary>
public static readonly IReadOnlyList<string> KnownCounters =
[
"stations", "depots", "edges", "edgesActive", "edgesBuilding", "locomotives", "cars", "trains", "lines", "trainsOnLine",
"mapPan", "mapZoom", "speedChanges", "trackPreviews",
];
public Dictionary<string, double> Counters { get; } = new(StringComparer.Ordinal);
public string Panel { get; set; } = NoPanel;
public double Get(string counter) => Counters.TryGetValue(counter, out double v) ? v : 0;
public void Set(string counter, double value) => Counters[counter] = value;
public void Add(string counter, double amount) => Counters[counter] = Get(counter) + amount;
/// <summary>Nome del contatore di un tipo di comando riuscito.</summary>
public static string CommandCounter(CommandType type) => CommandPrefix + type;
public static bool IsKnownCounter(string name) =>
KnownCounters.Contains(name)
|| (name.StartsWith(CommandPrefix, StringComparison.Ordinal) && Enum.TryParse<CommandType>(name[CommandPrefix.Length..], ignoreCase: false, out var t)
&& Enum.IsDefined(t) && t.ToString() == name[CommandPrefix.Length..]);
public TutorialFacts Clone()
{
var copy = new TutorialFacts { Panel = Panel };
foreach (var (k, v) in Counters) copy.Counters[k] = v;
return copy;
}
}
[JsonSourceGenerationOptions(PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase, PropertyNameCaseInsensitive = true,
UnmappedMemberHandling = JsonUnmappedMemberHandling.Disallow, ReadCommentHandling = JsonCommentHandling.Skip,
AllowTrailingCommas = true)]
[JsonSerializable(typeof(TutorialScript))]
internal sealed partial class TutorialJsonContext : JsonSerializerContext;