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: 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.Count == 0) errors.Add("nessun passo");
var ids = new HashSet(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;
}
}
/// 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) 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;