using System.Text.Json; using System.Text.Json.Serialization; using RailEnterprise.Core.Commands; namespace RailEnterprise.Client.Tutorial; /// /// Copione del tutorial guidato (assets/tutorial/tutorial.json, 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 Tutorial/Logic non dipendono da Godot e si provano nel harness dei test. /// public sealed class TutorialScript { /// Versione del formato del file (oggi 1). public int Version { get; init; } = 1; public List Steps { get; init; } = []; /// Indice del passo con l'id indicato, -1 se non c'è. public int IndexOf(string? id) => id is null ? -1 : Steps.FindIndex(s => s?.Id == id); /// Legge il copione dal testo JSON (commenti e virgole finali ammessi, campi sconosciuti rifiutati). public static TutorialScript Parse(string json) => JsonSerializer.Deserialize(json, TutorialJsonContext.Default.TutorialScript) ?? throw new JsonException("Copione del tutorial vuoto"); /// /// Elementi dell'interfaccia che un passo può evidenziare. Il client li risolve nei controlli /// (GameScreen.TutorialTarget); se un elemento non è visibile in quel momento si usa il /// ripiego del passo, altrimenti non si evidenzia nulla. /// public static readonly IReadOnlyList KnownTargets = BuildTargets(); private static List BuildTargets() { var list = new List { "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; } /// /// Controlla il copione: elenco e passi presenti (il JSON ammette null), id unici, testi presenti, /// elementi, contatori e pannelli noti. Restituisce gli errori in italiano. /// public List Validate() { var errors = new List(); if (Version != 1) errors.Add($"versione {Version} non supportata"); if (Steps is null) { errors.Add("elenco dei passi mancante"); return errors; } if (Steps.Count == 0) errors.Add("nessun passo"); var ids = new HashSet(StringComparer.Ordinal); for (int i = 0; i < Steps.Count; i++) { var step = Steps[i]; if (step is null) { errors.Add($"passo n. {i + 1} nullo"); continue; } 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; } } /// Passo del tutorial: testi (chiavi di traduzione), elemento da evidenziare, condizione di completamento. public sealed class TutorialStep { public required string Id { get; init; } /// Chiave del titolo per T() (testo italiano). public required string Title { get; init; } /// Chiave del testo per T() (testo italiano). public required string Text { get; init; } /// Elemento dell'interfaccia da evidenziare (vedi ), facoltativo. public string? Highlight { get; init; } /// Elemento da evidenziare quando il principale non è visibile (per esempio il pulsante che apre il pannello). public string? Fallback { get; init; } /// Condizione osservabile che completa il passo; senza condizione il passo è informativo (pulsante Avanti). public TutorialCondition? Done { get; init; } [JsonIgnore] public bool IsInformative => Done is null; } /// /// Condizione di completamento, valutata su fatti semplici che il client osserva (). /// Ha una sola forma tra: contatore (counter con atLeast, atMost e/o increase), /// pannello aperto (panel), tutte (all) o almeno una (any) di altre condizioni. /// increase confronta il contatore con il suo valore all'inizio del passo. /// 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? All { get; init; } public List? Any { get; init; } /// Vera se i fatti di adesso soddisfano la condizione; sono i fatti all'inizio del passo. 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 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) { if (c is null) errors.Add($"{where}: condizione nulla"); else c.Validate(where, errors); } } } } /// Fatti osservati dal client: contatori (entità della compagnia, comandi riusciti, azioni sulla mappa) e pannello aperto. public sealed class TutorialFacts { /// Pannello «nessuno» (barra degli strumenti senza selezione). public const string NoPanel = "none"; /// Prefisso dei contatori dei comandi riusciti: cmd: + nome di . public const string CommandPrefix = "cmd:"; /// Pannelli della barra degli strumenti, con i nomi in minuscolo dell'enumerazione Hud.Tool. public static readonly IReadOnlyList KnownPanels = [ NoPanel, "track", "station", "signal", "depot", "trains", "lines", "maintenance", "employment", "industries", "market", "companies", "climb", "finance", "demolish", ]; /// /// 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. /// public static readonly IReadOnlyList KnownCounters = [ "stations", "depots", "edges", "edgesActive", "edgesBuilding", "locomotives", "cars", "trains", "lines", "trainsOnLine", "mapPan", "mapZoom", "speedChanges", "trackPreviews", ]; public Dictionary 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; /// Nome del contatore di un tipo di comando riuscito. public static string CommandCounter(CommandType type) => CommandPrefix + type; public static bool IsKnownCounter(string name) => KnownCounters.Contains(name) || (name.StartsWith(CommandPrefix, StringComparison.Ordinal) && Enum.TryParse(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;