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>
206 lines
10 KiB
C#
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;
|