Unisce origin/main (audio, ere e obsolescenza, scheda dell'industria e schermata di connessione) e corregge i rilievi della revisione del tutorial (ADR 0023 aggiornato). - Chiave dell'avanzamento senza l'impronta del terreno, che il server ricalcola e che cambia giocando (città, industrie): origine della partita, seme, lato, anno d'inizio, regione e compagnia. Un tutorial ripreso dopo un anno di gioco ritrova la sua voce. - «Tutorial» apre una partita locale di prova sempre nuova in user://tutorial-server invece di riprendere l'autosalvataggio del giocatore e rifare il tutorial lì dentro; con salvataggi locali già presenti la casella «Mostra il tutorial» parte spenta. Casella e pulsante passano nella nuova ConnectScreen (MenuScreen non c'è più). - La casella spuntata vale anche su una voce chiusa o completata (stesso seme di una partita vecchia). - Contorno ritagliato dai contenitori a scorrimento, con l'elemento portato in vista; del tutto nascosto si usa il ripiego. - Pulsanti del riquadro senza fuoco: Invio e spazio restano alla partita (Costruisci, pausa) e non saltano il passo. - La base di «increase» è presa al completamento del passo precedente e gli esiti dei comandi si valutano subito: un binario costruito appena dopo conta per il passo nuovo. - Velocità contata solo dalle richieste di questo client. - Copione mancante o non valido segnalato nella partita; validazione dei null ammessi dal JSON. - Test: chiave stabile con impronta diversa, base al completamento, piano con la casella, null nel copione. 228 test (208 senza i lenti). Refs #45. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
224 lines
11 KiB
C#
224 lines
11 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: elenco e passi presenti (il JSON ammette <c>null</c>), 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 is null)
|
|
{
|
|
errors.Add("elenco dei passi mancante");
|
|
return errors;
|
|
}
|
|
if (Steps.Count == 0) errors.Add("nessun passo");
|
|
var ids = new HashSet<string>(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;
|
|
}
|
|
}
|
|
|
|
/// <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)
|
|
{
|
|
if (c is null) errors.Add($"{where}: condizione nulla");
|
|
else 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;
|