From fce49dbbcc4b3b4ba98a74811a755cd99facb429 Mon Sep 17 00:00:00 2001 From: penspanic Date: Wed, 30 Sep 2026 19:41:58 +0900 Subject: [PATCH 1/3] feat: add [Knob] and Datra.Lab, the UI-less core of the balance lab Datra.Lab lets a game tune its numbers by their outcome instead of by reading tables: mark fields as knobs, write one simulator class, and a batch of seeded bots plays the game on a forked copy of the data. - Datra/Attributes: [Knob] (label, group, unit, range, Row / EachRow, Set / Scale / Offset, Economy / Physics layer). It sits next to [TableData] so a data assembly needs nothing but Datra. - Knob schema by reflection over a data context, plus knobs declared in code for values that span several fields. - ContextForker / OverlayRawDataProvider: a fork is an ordinary TContext on an overlay provider. Reads fall through to a cached baseline, writes stay in the overlay, so nothing reaches the saved data. - ISimulator and SimRun: stages, ticks, progress, purchases, marks, explanations, stored physics outcomes, policy parameters. - BotRunner: N bots in parallel, one derived seed each, records returned in bot order so the result does not depend on scheduling. - ResultAggregator and LabResult: the JSON document the views draw from. - IOutcomeReader (read side only), InMemoryOutcomes, JsonlOutcomeReader. - Scenario (baseline + changed knobs), snapshots, FileSnapshotStore. Datra.Lab.Sample is a toy incremental game (floors with a fare, a fare box that is also the wallet, everything left behind on the way down) with its simulator; the tests and the web sample share it. Co-Authored-By: Claude Opus 5.5 --- Datra.Lab.Sample/Datra.Lab.Sample.csproj | 31 ++ Datra.Lab.Sample/DatraConfiguration.cs | 7 + Datra.Lab.Sample/DescentData.cs | 71 ++++ Datra.Lab.Sample/DescentLab.cs | 37 +++ Datra.Lab.Sample/DescentPhysics.cs | 102 ++++++ Datra.Lab.Sample/DescentSim.cs | 180 ++++++++++ Datra.Lab.Sample/Models/EconomyData.cs | 24 ++ Datra.Lab.Sample/Models/FloorData.cs | 33 ++ Datra.Lab.Sample/Models/UpgradeData.cs | 45 +++ Datra.Lab.Sample/Resources/Economy.yaml | 5 + Datra.Lab.Sample/Resources/Floors.yaml | 41 +++ Datra.Lab.Sample/Resources/Upgrades.yaml | 40 +++ Datra.Lab.Tests/BotRunnerTests.cs | 183 +++++++++++ Datra.Lab.Tests/Datra.Lab.Tests.csproj | 31 ++ Datra.Lab.Tests/DescentFixture.cs | 50 +++ Datra.Lab.Tests/ForkedContextTests.cs | 157 +++++++++ Datra.Lab.Tests/KnobSchemaTests.cs | 142 ++++++++ Datra.Lab.Tests/SimRunTests.cs | 308 ++++++++++++++++++ Datra.Lab.Tests/SnapshotTests.cs | 85 +++++ Datra.Lab/Context/ContextForker.cs | 77 +++++ Datra.Lab/Context/OverlayRawDataProvider.cs | 75 +++++ Datra.Lab/Context/RawDataSnapshot.cs | 98 ++++++ Datra.Lab/Datra.Lab.csproj | 20 ++ Datra.Lab/Knobs/ForkedData.cs | 31 ++ Datra.Lab/Knobs/KnobBuilder.cs | 84 +++++ Datra.Lab/Knobs/KnobInfo.cs | 55 ++++ Datra.Lab/Knobs/KnobSchemaReader.cs | 344 ++++++++++++++++++++ Datra.Lab/LabEngine.cs | 291 +++++++++++++++++ Datra.Lab/LabJson.cs | 40 +++ Datra.Lab/LabOptions.cs | 115 +++++++ Datra.Lab/LabSchema.cs | 69 ++++ Datra.Lab/Outcomes/IOutcomeReader.cs | 111 +++++++ Datra.Lab/Outcomes/PhysicsKey.cs | 68 ++++ Datra.Lab/Results/LabCheck.cs | 51 +++ Datra.Lab/Results/LabResult.cs | 184 +++++++++++ Datra.Lab/Results/ResultAggregator.cs | 343 +++++++++++++++++++ Datra.Lab/Scenarios/Scenario.cs | 33 ++ Datra.Lab/Scenarios/Snapshots.cs | 128 ++++++++ Datra.Lab/Simulation/BotRecord.cs | 143 ++++++++ Datra.Lab/Simulation/BotRunner.cs | 83 +++++ Datra.Lab/Simulation/ISimulator.cs | 20 ++ Datra.Lab/Simulation/RunSettings.cs | 35 ++ Datra.Lab/Simulation/SimRandom.cs | 60 ++++ Datra.Lab/Simulation/SimRun.cs | 173 ++++++++++ Datra.sln | 42 +++ Datra/Attributes/KnobAttribute.cs | 100 ++++++ Datra/Attributes/KnobAttribute.cs.meta | 2 + 47 files changed, 4447 insertions(+) create mode 100644 Datra.Lab.Sample/Datra.Lab.Sample.csproj create mode 100644 Datra.Lab.Sample/DatraConfiguration.cs create mode 100644 Datra.Lab.Sample/DescentData.cs create mode 100644 Datra.Lab.Sample/DescentLab.cs create mode 100644 Datra.Lab.Sample/DescentPhysics.cs create mode 100644 Datra.Lab.Sample/DescentSim.cs create mode 100644 Datra.Lab.Sample/Models/EconomyData.cs create mode 100644 Datra.Lab.Sample/Models/FloorData.cs create mode 100644 Datra.Lab.Sample/Models/UpgradeData.cs create mode 100644 Datra.Lab.Sample/Resources/Economy.yaml create mode 100644 Datra.Lab.Sample/Resources/Floors.yaml create mode 100644 Datra.Lab.Sample/Resources/Upgrades.yaml create mode 100644 Datra.Lab.Tests/BotRunnerTests.cs create mode 100644 Datra.Lab.Tests/Datra.Lab.Tests.csproj create mode 100644 Datra.Lab.Tests/DescentFixture.cs create mode 100644 Datra.Lab.Tests/ForkedContextTests.cs create mode 100644 Datra.Lab.Tests/KnobSchemaTests.cs create mode 100644 Datra.Lab.Tests/SimRunTests.cs create mode 100644 Datra.Lab.Tests/SnapshotTests.cs create mode 100644 Datra.Lab/Context/ContextForker.cs create mode 100644 Datra.Lab/Context/OverlayRawDataProvider.cs create mode 100644 Datra.Lab/Context/RawDataSnapshot.cs create mode 100644 Datra.Lab/Datra.Lab.csproj create mode 100644 Datra.Lab/Knobs/ForkedData.cs create mode 100644 Datra.Lab/Knobs/KnobBuilder.cs create mode 100644 Datra.Lab/Knobs/KnobInfo.cs create mode 100644 Datra.Lab/Knobs/KnobSchemaReader.cs create mode 100644 Datra.Lab/LabEngine.cs create mode 100644 Datra.Lab/LabJson.cs create mode 100644 Datra.Lab/LabOptions.cs create mode 100644 Datra.Lab/LabSchema.cs create mode 100644 Datra.Lab/Outcomes/IOutcomeReader.cs create mode 100644 Datra.Lab/Outcomes/PhysicsKey.cs create mode 100644 Datra.Lab/Results/LabCheck.cs create mode 100644 Datra.Lab/Results/LabResult.cs create mode 100644 Datra.Lab/Results/ResultAggregator.cs create mode 100644 Datra.Lab/Scenarios/Scenario.cs create mode 100644 Datra.Lab/Scenarios/Snapshots.cs create mode 100644 Datra.Lab/Simulation/BotRecord.cs create mode 100644 Datra.Lab/Simulation/BotRunner.cs create mode 100644 Datra.Lab/Simulation/ISimulator.cs create mode 100644 Datra.Lab/Simulation/RunSettings.cs create mode 100644 Datra.Lab/Simulation/SimRandom.cs create mode 100644 Datra.Lab/Simulation/SimRun.cs create mode 100644 Datra/Attributes/KnobAttribute.cs create mode 100644 Datra/Attributes/KnobAttribute.cs.meta diff --git a/Datra.Lab.Sample/Datra.Lab.Sample.csproj b/Datra.Lab.Sample/Datra.Lab.Sample.csproj new file mode 100644 index 0000000..e01f0e8 --- /dev/null +++ b/Datra.Lab.Sample/Datra.Lab.Sample.csproj @@ -0,0 +1,31 @@ + + + + netstandard2.1 + latest + enable + Datra.Lab.Sample + + + + + + + + + + + + + + + + + + + + diff --git a/Datra.Lab.Sample/DatraConfiguration.cs b/Datra.Lab.Sample/DatraConfiguration.cs new file mode 100644 index 0000000..85748ed --- /dev/null +++ b/Datra.Lab.Sample/DatraConfiguration.cs @@ -0,0 +1,7 @@ +using Datra.Attributes; + +[assembly: DatraConfiguration("Descent", + Namespace = "Datra.Lab.Sample.Generated", + EnableLocalization = false, + EmitPhysicalFiles = false +)] diff --git a/Datra.Lab.Sample/DescentData.cs b/Datra.Lab.Sample/DescentData.cs new file mode 100644 index 0000000..02a02f9 --- /dev/null +++ b/Datra.Lab.Sample/DescentData.cs @@ -0,0 +1,71 @@ +#nullable enable +using System; +using System.Collections.Generic; +using System.IO; +using System.Linq; +using System.Reflection; +using Datra.Lab.Sample.Generated; +using Datra.Lab.Sample.Models; + +namespace Datra.Lab.Sample +{ + /// + /// The toy game's data files (embedded in this assembly) and the few helpers that read + /// the loaded tables the way a game's own code would. + /// + public static class DescentData + { + private const string Prefix = "Descent/"; + + /// File name → YAML text, as shipped. + public static IReadOnlyDictionary Files() + { + var assembly = typeof(DescentData).GetTypeInfo().Assembly; + var files = new Dictionary(StringComparer.Ordinal); + foreach (var name in assembly.GetManifestResourceNames().Where(n => n.StartsWith(Prefix, StringComparison.Ordinal))) + { + using var stream = assembly.GetManifestResourceStream(name)!; + using var reader = new StreamReader(stream); + files[name.Substring(Prefix.Length)] = reader.ReadToEnd(); + } + return files; + } + + /// Write the data files into so a file provider can serve them. + public static string WriteTo(string directory) + { + Directory.CreateDirectory(directory); + foreach (var file in Files()) + File.WriteAllText(Path.Combine(directory, file.Key), file.Value); + return directory; + } + + /// Floors top to bottom, in file order. + public static IReadOnlyList FloorsInOrder(DescentContext data) => + data.Floor.LoadedItems.Values.ToList(); + + /// The factor each floor's value multiplier grows by, on average. + public static double ValueGrowth(DescentContext data) + { + var floors = FloorsInOrder(data); + if (floors.Count < 2 || floors[0].ValueMultiplier <= 0) return 1; + return Math.Pow(floors[floors.Count - 1].ValueMultiplier / floors[0].ValueMultiplier, 1.0 / (floors.Count - 1)); + } + + /// + /// Re-slope the value multipliers to grow by per floor. Each + /// floor keeps its hand-tuned distance from the curve: only the slope changes. + /// + public static void SetValueGrowth(DescentContext data, double growth) + { + var current = ValueGrowth(data); + if (current <= 0 || growth <= 0) return; + var floors = FloorsInOrder(data); + for (var i = 0; i < floors.Count; i++) + { + var value = (float)(floors[i].ValueMultiplier * Math.Pow(growth / current, i)); + ForkedData.Set(floors[i], f => f.ValueMultiplier, value); + } + } + } +} diff --git a/Datra.Lab.Sample/DescentLab.cs b/Datra.Lab.Sample/DescentLab.cs new file mode 100644 index 0000000..6c18e66 --- /dev/null +++ b/Datra.Lab.Sample/DescentLab.cs @@ -0,0 +1,37 @@ +#nullable enable +using Datra.Lab.Sample.Generated; + +namespace Datra.Lab.Sample +{ + /// The toy game's lab setup, shared by the web sample and the tests. + public static class DescentLab + { + /// + /// Policies, the policy parameter, the curve knob, the checks: everything the game adds + /// on top of its [Knob] attributes and its simulator. + /// + public static void Configure(LabOptions lab) + { + lab.Title = "Descent · balance lab"; + lab.Bots = 40; + + lab.Policy(DescentSim.Efficient, "Efficient", "Buys what gets it down soonest, saves otherwise"); + lab.Policy(DescentSim.Cheap, "Cheapest first", "Buys whatever it can afford"); + lab.Policy(DescentSim.RandomPick, "Random", "Picks among the upgrades that pay back"); + lab.PolicyParam("shopSeconds", "Time between runs", @default: 8, min: 2, max: 30, step: 1, unit: "s"); + + // One knob over a whole column: an attribute cannot say "re-slope these five rows". + lab.Knobs(knobs => knobs.Add( + "Depth value growth", + read: DescentData.ValueGrowth, + write: DescentData.SetValueGrowth, + min: 1.4, max: 3, step: 0.05, + group: "Floors", unit: "×/floor", + hint: "How much more each floor pays than the one above", + id: "Floors.ValueGrowth")); + + lab.Check("First purchase", bot => bot.FirstPurchaseSeconds, "<= 60", unit: "s"); + lab.Check("Longest run", bot => bot.LongestTickSeconds("run"), "<= 90", unit: "s"); + } + } +} diff --git a/Datra.Lab.Sample/DescentPhysics.cs b/Datra.Lab.Sample/DescentPhysics.cs new file mode 100644 index 0000000..f630f16 --- /dev/null +++ b/Datra.Lab.Sample/DescentPhysics.cs @@ -0,0 +1,102 @@ +#nullable enable +using System; +using System.Collections.Generic; +using System.Linq; +using Datra.Lab.Sample.Generated; +using Datra.Lab.Sample.Models; + +namespace Datra.Lab.Sample +{ + /// What happened to one bottle on the stairs: the unit the physics cache stores. + public sealed class BottleOutcome + { + /// Steps the bottle survived. + public int Steps { get; set; } + + /// It reached the bottom in one piece. + public bool Intact { get; set; } + + /// It came to rest on the landing. + public bool StoppedOnLanding { get; set; } + + /// How long the bottle was in play. + public double Seconds { get; set; } + } + + /// + /// Stands in for a game's headless physics batch. A real game runs its engine overnight and + /// stores the outcomes; this fills the same kind of pools from a few lines of arithmetic so + /// the sample has something to draw from. + /// + public static class DescentPhysics + { + public const string Version = "toy-1"; + public const int SamplesPerKey = 64; + + /// The physics state a bottle is rolled in. Only inputs that change the outcome belong here. + public static PhysicsKey Key(string floor, int push, int wrap) => + PhysicsKey.Of(("floor", floor), ("push", push), ("wrap", wrap)); + + /// Roll every state a bot can pass through and keep the outcomes. + public static InMemoryOutcomes Bake(DescentContext data) + { + var outcomes = new InMemoryOutcomes(Version); + var economy = data.Economy.Current ?? new EconomyData(); + var upgrades = data.Upgrade.LoadedItems; + var push = upgrades["push"]; + var wrap = upgrades["wrap"]; + var floors = DescentData.FloorsInOrder(data); + + for (var f = 0; f < floors.Count; f++) + { + for (var p = 0; p <= push.MaxLevel; p++) + { + for (var w = 0; w <= wrap.MaxLevel; w++) + { + // One fixed seed per state: baking twice gives the same pools. + var random = new SimRandom(1_000_003L * (f + 1) + 1_009L * p + w); + var pool = Enumerable.Range(0, SamplesPerKey) + .Select(_ => Roll(floors[f], p * push.Amount, w * wrap.Amount, economy.GlassToughness, random)) + .ToList(); + outcomes.Add(Key(floors[f].Id, p, w), pool); + } + } + } + return outcomes; + } + + private static BottleOutcome Roll(FloorData floor, double reach, double padding, double toughness, SimRandom random) + { + // Each step is a chance to break. Pushing harder carries the bottle further before + // it slows down; wrap and tougher glass make every step kinder. + var breakChance = 0.20 / (toughness * (1 + padding)); + var carry = 3.0 + reach * 4.0; + var steps = 0; + var stopped = false; + + while (steps < floor.Steps) + { + if (random.Chance(breakChance)) break; + steps++; + if (steps == floor.LandingStep && random.Chance(0.55)) + { + stopped = true; + break; + } + if (steps > carry && random.Chance(0.28)) + { + stopped = true; + break; + } + } + + return new BottleOutcome + { + Steps = steps, + Intact = steps >= floor.Steps, + StoppedOnLanding = stopped && steps == floor.LandingStep && floor.LandingStep > 0, + Seconds = 3.0 + steps * 0.8, + }; + } + } +} diff --git a/Datra.Lab.Sample/DescentSim.cs b/Datra.Lab.Sample/DescentSim.cs new file mode 100644 index 0000000..d510e1c --- /dev/null +++ b/Datra.Lab.Sample/DescentSim.cs @@ -0,0 +1,180 @@ +#nullable enable +using System; +using System.Collections.Generic; +using System.Linq; +using Datra.Lab.Sample.Generated; +using Datra.Lab.Sample.Models; + +namespace Datra.Lab.Sample +{ + /// + /// One bot playing the toy game from the top floor to the platform. + /// + /// + /// The rules a balance tool has to get right are all here in a few lines: + /// + /// The fare box is the wallet. Buying an upgrade takes coins out of the box, so every + /// purchase pushes the shutter back down. + /// When the box holds the fare the shutter opens and the bot goes down. Whatever is + /// in the box stays there: every floor starts with an empty box. + /// Account upgrades come along. Floor devices stay on the floor they were bought on. + /// + /// A real game would call its own earnings and shop code instead of the small + /// Earn and Cost methods below. + /// + public sealed class DescentSim : ISimulator + { + public const string Efficient = "efficient"; + public const string Cheap = "cheap"; + public const string RandomPick = "random"; + + public void Play(DescentContext data, SimRun run) + { + var economy = data.Economy.Current ?? new EconomyData(); + var upgrades = data.Upgrade.LoadedItems.Values.ToList(); + var floors = DescentData.FloorsInOrder(data); + var shopSeconds = run.Param("shopSeconds", 8); + + var account = upgrades.Where(u => u.Scope == UpgradeScope.Account).ToDictionary(u => u.Id, _ => 0); + var markedIntact = false; + + for (var f = 0; f < floors.Count && !run.OutOfTime; f++) + { + var floor = floors[f]; + run.Stage(floor.Id, targetSeconds: floor.TargetMinutes * 60, label: floor.Id + " " + floor.Name); + + // A new floor: an empty fare box and no devices installed yet. + var wallet = 0.0; + var devices = upgrades.Where(u => u.Scope == UpgradeScope.Floor).ToDictionary(u => u.Id, _ => 0); + int Level(UpgradeData u) => u.Scope == UpgradeScope.Account ? account[u.Id] : devices[u.Id]; + + double earnedHere = 0, playedHere = 0; + int bottlesHere = 0, landedHere = 0; + + while (!run.OutOfTime) + { + // One run: every bottle in the line gets one stored physics outcome. + var key = DescentPhysics.Key(floor.Id, account["push"], account["wrap"]); + var bottles = economy.BottlesPerRun + account["queue"]; + double earned = 0, seconds = 0; + for (var b = 0; b < bottles; b++) + { + var outcome = run.Outcome(key); + earned += Earn(economy, floor, outcome, devices, upgrades); + seconds += outcome.Seconds; + bottlesHere++; + if (outcome.StoppedOnLanding) landedHere++; + if (outcome.Intact && !markedIntact) + { + markedIntact = true; + run.Mark("first intact bottle"); + } + } + + wallet += earned; + earnedHere += earned; + playedHere += seconds + shopSeconds; + run.Tick(seconds, earned); + run.Progress(wallet / floor.Fare); + + // The shutter opens as soon as the box holds the fare. The coins stay behind. + if (wallet >= floor.Fare) break; + + run.Tick(shopSeconds, 0, "shop"); + var rate = earnedHere / playedHere; + while (Pick(run, upgrades, Level, floor, floors, f, wallet, rate) is { } choice) + { + var cost = Cost(choice, Level(choice), floor); + wallet -= cost; + if (choice.Scope == UpgradeScope.Account) account[choice.Id]++; + else devices[choice.Id]++; + run.Purchase(choice.Id, cost, + group: choice.Scope == UpgradeScope.Account ? "Account" : "Floor device", + label: choice.Name + " Lv" + Level(choice)); + run.Progress(wallet / floor.Fare); + } + } + + if (bottlesHere > 0 && landedHere > bottlesHere * 0.25) + { + run.Explain(floor.Id, "More than a quarter of the bottles stop on the landing, which cuts their step count short."); + } + } + } + + /// The game's pricing rule: what one bottle's outcome is worth. + public static double Earn( + EconomyData economy, FloorData floor, BottleOutcome outcome, + IReadOnlyDictionary devices, IReadOnlyList upgrades) + { + var carpet = upgrades.First(u => u.Id == "carpet"); + var box = upgrades.First(u => u.Id == "box"); + var steps = outcome.Steps * economy.StepValue * (1 + carpet.Amount * devices["carpet"]); + var bonus = outcome.Intact ? economy.IntactBonus * (1 + box.Amount * devices["box"]) : 0; + return (steps + bonus) * floor.ValueMultiplier; + } + + /// The game's price rule. Floor devices cost more the deeper the floor. + public static double Cost(UpgradeData upgrade, int level, FloorData floor) + { + var price = upgrade.BaseCost * Math.Pow(upgrade.CostGrowth, level); + if (upgrade.Scope == UpgradeScope.Floor) price *= floor.ValueMultiplier; + return Math.Round(price); + } + + /// What the bot buys next, or null when it would rather save for the fare. + private static UpgradeData? Pick( + SimRun run, List upgrades, Func level, + FloorData floor, IReadOnlyList floors, int floorIndex, double wallet, double rate) + { + var affordable = upgrades + .Where(u => level(u) < u.MaxLevel && Cost(u, level(u), floor) <= wallet) + .ToList(); + if (affordable.Count == 0) return null; + + switch (run.Policy) + { + case Cheap: + // Buys whatever is cheapest as soon as it can. Finite: levels run out. + return affordable.OrderBy(u => Cost(u, level(u), floor)).First(); + + case RandomPick: + { + var worth = affordable.Where(u => PaysBack(u, level(u), floor, floors, floorIndex, wallet, rate)).ToList(); + return worth.Count > 0 && run.Random.Chance(0.6) ? run.Random.Pick(worth) : null; + } + + default: + // Most extra earnings per coin, among the upgrades that get the bot down sooner. + return affordable + .Where(u => PaysBack(u, level(u), floor, floors, floorIndex, wallet, rate)) + .OrderByDescending(u => u.Amount / Cost(u, level(u), floor)) + .FirstOrDefault(); + } + } + + /// + /// Spending sets the fare box back. It is worth it when the faster earning makes up the + /// cost before the coins would have been needed: on this floor for a device, over the + /// rest of the game for an account upgrade. + /// + private static bool PaysBack( + UpgradeData upgrade, int level, FloorData floor, IReadOnlyList floors, int floorIndex, + double wallet, double rate) + { + if (rate <= 0) return false; + var cost = Cost(upgrade, level, floor); + var toGo = floor.Fare - wallet; + if (upgrade.Scope == UpgradeScope.Account) + { + // Later floors pay more per second, so their fares take less time than the coins suggest. + for (var i = floorIndex + 1; i < floors.Count; i++) + toGo += floors[i].Fare * floor.ValueMultiplier / floors[i].ValueMultiplier; + } + + var without = toGo / rate; + var with = (toGo + cost) / (rate * (1 + upgrade.Amount)); + return with < without; + } + } +} diff --git a/Datra.Lab.Sample/Models/EconomyData.cs b/Datra.Lab.Sample/Models/EconomyData.cs new file mode 100644 index 0000000..bb8d57e --- /dev/null +++ b/Datra.Lab.Sample/Models/EconomyData.cs @@ -0,0 +1,24 @@ +using Datra.Attributes; + +namespace Datra.Lab.Sample.Models +{ + /// The pricing rules of the toy game. + [SingleData("Economy.yaml", Format = DataFormat.Yaml)] + public partial class EconomyData + { + /// Coins for every step a bottle survives. + [Knob("Step value", Group = "Rewards", Unit = "coins/step", Min = 1, Max = 15, Step = 0.5)] + public float StepValue { get; set; } = 5f; + + /// Coins for a bottle that reaches the bottom in one piece. + [Knob("Intact bonus", Group = "Rewards", Unit = "coins", Min = 0, Max = 200, Step = 5)] + public float IntactBonus { get; set; } = 40f; + + /// Bottles in the line at the start of the game. + public int BottlesPerRun { get; set; } = 3; + + /// How easily glass breaks. Decides the stored outcomes, so it is a physics knob. + [Knob("Glass toughness", Group = "Rewards", Unit = "×", Min = 0.5, Max = 2, Step = 0.05, Layer = KnobLayer.Physics)] + public float GlassToughness { get; set; } = 1f; + } +} diff --git a/Datra.Lab.Sample/Models/FloorData.cs b/Datra.Lab.Sample/Models/FloorData.cs new file mode 100644 index 0000000..07f70f4 --- /dev/null +++ b/Datra.Lab.Sample/Models/FloorData.cs @@ -0,0 +1,33 @@ +using Datra.Attributes; +using Datra.Interfaces; + +namespace Datra.Lab.Sample.Models +{ + /// + /// One floor of the toy game. The player fills the fare box to open the shutter and go down. + /// + [TableData("Floors.yaml", Format = DataFormat.Yaml)] + public partial class FloorData : ITableData + { + public string Id { get; set; } = string.Empty; + + public string Name { get; set; } = string.Empty; + + /// Coins the fare box must hold before the shutter opens. + [Knob("Fare", Group = "Floors", Unit = "coins", EachRow = true, + Hint = "Coins the fare box must hold before the shutter opens")] + public int Fare { get; set; } + + /// Everything earned on this floor is multiplied by this. + public float ValueMultiplier { get; set; } = 1f; + + /// How long the floor is meant to take. + public float TargetMinutes { get; set; } + + /// Number of steps on the staircase. + public int Steps { get; set; } + + /// The step that is a landing, where bottles tend to stop. Zero for none. + public int LandingStep { get; set; } + } +} diff --git a/Datra.Lab.Sample/Models/UpgradeData.cs b/Datra.Lab.Sample/Models/UpgradeData.cs new file mode 100644 index 0000000..ca50225 --- /dev/null +++ b/Datra.Lab.Sample/Models/UpgradeData.cs @@ -0,0 +1,45 @@ +using Datra.Attributes; +using Datra.Interfaces; + +namespace Datra.Lab.Sample.Models +{ + public enum UpgradeScope + { + /// Kept for the whole game. + Account, + + /// A device installed on one floor: bought again on every floor. + Floor + } + + /// Something the bot can buy with coins from the fare box. + [TableData("Upgrades.yaml", Format = DataFormat.Yaml)] + public partial class UpgradeData : ITableData + { + public string Id { get; set; } = string.Empty; + + public string Name { get; set; } = string.Empty; + + public UpgradeScope Scope { get; set; } + + /// Price of the first level. + [Knob("Upgrade prices", Group = "Upgrades", Unit = "×", Min = 0.25, Max = 3, Step = 0.05, Apply = KnobApply.Scale, + Hint = "Multiplies the first-level price of every upgrade")] + public float BaseCost { get; set; } + + /// Each level costs this many times the one before. + public float CostGrowth { get; set; } = 1.5f; + + public int MaxLevel { get; set; } = 5; + + /// + /// Gain per level, as a fraction. For the economy upgrades this is the rule the game + /// applies; for the physics ones it is only what the bot expects when it shops. + /// + [Knob("Carpet value per level", Group = "Upgrades", Unit = "×/level", Min = 0, Max = 1, Step = 0.01, Row = "carpet", + Hint = "Extra step value per carpet level, on the floor it is laid on")] + [Knob("Push: steps per level", Group = "Upgrades", Unit = "steps/level", Min = 0, Max = 1, Step = 0.01, Row = "push", + Layer = KnobLayer.Physics, Hint = "How much further a harder push carries a bottle")] + public float Amount { get; set; } + } +} diff --git a/Datra.Lab.Sample/Resources/Economy.yaml b/Datra.Lab.Sample/Resources/Economy.yaml new file mode 100644 index 0000000..37c2200 --- /dev/null +++ b/Datra.Lab.Sample/Resources/Economy.yaml @@ -0,0 +1,5 @@ +# Pricing rules of the toy game. +StepValue: 5 +IntactBonus: 40 +BottlesPerRun: 3 +GlassToughness: 1 diff --git a/Datra.Lab.Sample/Resources/Floors.yaml b/Datra.Lab.Sample/Resources/Floors.yaml new file mode 100644 index 0000000..5fab42a --- /dev/null +++ b/Datra.Lab.Sample/Resources/Floors.yaml @@ -0,0 +1,41 @@ +# Floors of the toy game the lab sample tunes. Fill the fare box to go down one floor. +- Id: B1 + Name: Ticket hall + Fare: 280 + ValueMultiplier: 1 + TargetMinutes: 4 + Steps: 8 + LandingStep: 0 + +- Id: B2 + Name: Concourse + Fare: 600 + ValueMultiplier: 2.2 + TargetMinutes: 5 + Steps: 10 + LandingStep: 0 + +# The landing halfway down is where bottles like to stop. +- Id: B3 + Name: Transfer + Fare: 2000 + ValueMultiplier: 4.5 + TargetMinutes: 6 + Steps: 12 + LandingStep: 6 + +- Id: B4 + Name: Mezzanine + Fare: 9500 + ValueMultiplier: 9 + TargetMinutes: 7 + Steps: 12 + LandingStep: 0 + +- Id: B5 + Name: Platform + Fare: 32000 + ValueMultiplier: 18 + TargetMinutes: 8 + Steps: 14 + LandingStep: 0 diff --git a/Datra.Lab.Sample/Resources/Upgrades.yaml b/Datra.Lab.Sample/Resources/Upgrades.yaml new file mode 100644 index 0000000..1f92f84 --- /dev/null +++ b/Datra.Lab.Sample/Resources/Upgrades.yaml @@ -0,0 +1,40 @@ +# Account upgrades stay for the whole game. Floor devices are bought again on every floor. +- Id: push + Name: Push power + Scope: Account + BaseCost: 120 + CostGrowth: 2.1 + MaxLevel: 5 + Amount: 0.35 + +- Id: wrap + Name: Bubble wrap + Scope: Account + BaseCost: 260 + CostGrowth: 2.6 + MaxLevel: 3 + Amount: 0.2 + +- Id: queue + Name: Longer line + Scope: Account + BaseCost: 400 + CostGrowth: 3.2 + MaxLevel: 3 + Amount: 0.33 + +- Id: carpet + Name: Carpet + Scope: Floor + BaseCost: 90 + CostGrowth: 1.9 + MaxLevel: 4 + Amount: 0.25 + +- Id: box + Name: Catch box + Scope: Floor + BaseCost: 150 + CostGrowth: 2.2 + MaxLevel: 3 + Amount: 0.5 diff --git a/Datra.Lab.Tests/BotRunnerTests.cs b/Datra.Lab.Tests/BotRunnerTests.cs new file mode 100644 index 0000000..883ccd6 --- /dev/null +++ b/Datra.Lab.Tests/BotRunnerTests.cs @@ -0,0 +1,183 @@ +using Datra.Lab.Sample; +using Datra.Lab.Sample.Generated; +using Xunit; + +namespace Datra.Lab.Tests; + +public class BotRunnerTests +{ + /// The result as JSON, minus the wall-clock time — the one part allowed to differ. + private static string Fingerprint(LabResult result) + { + var timing = result.Timing; + result.Timing = null; + try { return LabJson.Serialize(result); } + finally { result.Timing = timing; } + } + + [Fact] + public async Task Same_seed_gives_the_same_result() + { + using var lab = new DescentFixture(); + var scenario = new Scenario { Seed = 7, Bots = 24, Changes = { ["EconomyData.StepValue"] = 8 } }; + + var first = await lab.Engine.RunAsync(scenario); + var second = await lab.Engine.RunAsync(scenario); + + Assert.Equal(Fingerprint(first), Fingerprint(second)); + Assert.Equal(24, first.Finished); + } + + [Fact] + public async Task Result_does_not_depend_on_how_many_threads_ran_the_bots() + { + using var serial = new DescentFixture(o => o.MaxParallelism = 1); + using var parallel = new DescentFixture(o => o.MaxParallelism = 8); + var scenario = new Scenario { Seed = 3, Bots = 32 }; + + var one = await serial.Engine.RunAsync(scenario); + var many = await parallel.Engine.RunAsync(scenario); + + Assert.Equal(Fingerprint(one), Fingerprint(many)); + } + + [Fact] + public async Task A_different_seed_gives_a_different_result() + { + using var lab = new DescentFixture(); + + var a = await lab.Engine.RunAsync(new Scenario { Seed = 1 }); + var b = await lab.Engine.RunAsync(new Scenario { Seed = 2 }); + + Assert.NotEqual(a.Total!.Median, b.Total!.Median); + } + + [Fact] + public async Task Each_bot_replays_exactly_from_its_own_seed() + { + using var lab = new DescentFixture(); + var data = await lab.Engine.ForkAsync(); + var outcomes = DescentPhysics.Bake(data); + var settings = new RunSettings { Bots = 12, Seed = 5, Policy = DescentSim.Efficient }; + + var batch = BotRunner.Run(new DescentSim(), data, settings, outcomes); + var alone = BotRunner.RunOne(new DescentSim(), data, settings, 9, outcomes); + + Assert.Equal(SimRandom.Derive(5, 9), batch[9].Seed); + Assert.Equal(batch[9].Seed, alone.Seed); + Assert.Equal(batch[9].TotalSeconds, alone.TotalSeconds); + Assert.Equal(batch[9].Purchases.Select(p => (p.Time, p.Id)), alone.Purchases.Select(p => (p.Time, p.Id))); + Assert.Equal(batch[9].Ticks.Select(t => t.Earned), alone.Ticks.Select(t => t.Earned)); + Assert.Equal(Enumerable.Range(0, 12), batch.Select(r => r.Bot)); + Assert.Equal(12, batch.Select(r => r.Seed).Distinct().Count()); + } + + [Fact] + public async Task Bots_share_luck_across_scenarios_so_a_knob_is_the_only_difference() + { + using var lab = new DescentFixture(); + var data = await lab.Engine.ForkAsync(); + var outcomes = DescentPhysics.Bake(data); + var settings = new RunSettings { Bots = 6, Seed = 11, Policy = DescentSim.Cheap }; + + var a = BotRunner.Run(new DescentSim(), data, settings, outcomes); + var b = BotRunner.Run(new DescentSim(), data, settings, outcomes); + + Assert.Equal(a.Select(r => r.Seed), b.Select(r => r.Seed)); + Assert.Equal(a.Select(r => r.TotalEarned), b.Select(r => r.TotalEarned)); + } + + [Fact] + public async Task Policy_and_policy_parameters_reach_the_simulator() + { + using var lab = new DescentFixture(); + + var quick = await lab.Engine.RunAsync(new Scenario { PolicyParams = { ["shopSeconds"] = 2 } }); + var slow = await lab.Engine.RunAsync(new Scenario { PolicyParams = { ["shopSeconds"] = 30 } }); + var cheap = await lab.Engine.RunAsync(new Scenario { Policy = DescentSim.Cheap }); + + Assert.True(quick.Total!.Median < slow.Total!.Median); + Assert.True(cheap.Purchases.CountMedian > quick.Purchases.CountMedian); + Assert.Equal(DescentSim.Cheap, cheap.Scenario.Policy); + Assert.Equal(2, quick.Scenario.PolicyParams["shopSeconds"]); + + await Assert.ThrowsAsync(() => lab.Engine.RunAsync(new Scenario { Policy = "nope" })); + await Assert.ThrowsAsync(() => lab.Engine.RunAsync(new Scenario { PolicyParams = { ["nope"] = 1 } })); + } + + [Fact] + public async Task A_cheaper_fare_shortens_that_floor_and_the_run() + { + using var lab = new DescentFixture(); + + var baseline = await lab.Engine.RunAsync(new Scenario()); + var cheaper = await lab.Engine.RunAsync(new Scenario { Changes = { ["FloorData[B3].Fare"] = 800 } }); + + var before = baseline.Stages.Single(s => s.Id == "B3").Median!.Value; + var after = cheaper.Stages.Single(s => s.Id == "B3").Median!.Value; + Assert.True(after < before, $"B3 took {after}s with the cheaper fare, {before}s before"); + Assert.True(cheaper.Total!.Median < baseline.Total!.Median); + // The floors above B3 are played with the same luck and the same numbers. + Assert.Equal(baseline.Stages[0].Median, cheaper.Stages[0].Median); + } + + [Fact] + public async Task A_knob_left_on_its_baseline_is_not_a_change() + { + using var lab = new DescentFixture(); + + var plain = await lab.Engine.RunAsync(new Scenario()); + var same = await lab.Engine.RunAsync(new Scenario { Changes = { ["EconomyData.StepValue"] = 5 } }); + + Assert.Empty(same.Scenario.Changes); + Assert.Equal(Fingerprint(plain), Fingerprint(same)); + } + + [Fact] + public void A_bot_that_never_finishes_is_stopped_at_the_time_cap_and_reported() + { + var records = BotRunner.Run(new Stuck(), new DescentContext(new Datra.Providers.FileSystemRawDataProvider(".")), + new RunSettings { Bots = 3, MaxSimSeconds = 600 }); + var result = ResultAggregator.Aggregate(records); + + Assert.Equal(0, result.Finished); + Assert.Null(result.Total); + Assert.All(records, r => Assert.True(r.TotalSeconds >= 600)); + Assert.Equal(3, result.Stages[0].Reached); + Assert.Equal(0, result.Stages[0].Completed); + Assert.Null(result.Stages[0].Median); + var problem = Assert.Single(result.Problems); + Assert.Equal("unfinished", problem.Kind); + Assert.Equal(3, problem.Bots); + } + + [Fact] + public void A_simulator_that_never_advances_time_is_cut_off_and_reported() + { + var records = BotRunner.Run(new Frozen(), new DescentContext(new Datra.Providers.FileSystemRawDataProvider(".")), + new RunSettings { Bots = 2, MaxRecords = 1000 }); + + Assert.All(records, r => Assert.False(r.Finished)); + Assert.All(records, r => Assert.Contains("looping", r.Error)); + var result = ResultAggregator.Aggregate(records); + Assert.Equal("error", result.Problems[0].Kind); + Assert.Equal(2, result.Problems[0].Bots); + } + + private sealed class Stuck : ISimulator + { + public void Play(DescentContext data, SimRun run) + { + run.Stage("only"); + while (!run.OutOfTime) run.Tick(30, 0); + } + } + + private sealed class Frozen : ISimulator + { + public void Play(DescentContext data, SimRun run) + { + while (!run.OutOfTime) run.Tick(0, 1); + } + } +} diff --git a/Datra.Lab.Tests/Datra.Lab.Tests.csproj b/Datra.Lab.Tests/Datra.Lab.Tests.csproj new file mode 100644 index 0000000..f85a2b6 --- /dev/null +++ b/Datra.Lab.Tests/Datra.Lab.Tests.csproj @@ -0,0 +1,31 @@ + + + + net9.0 + enable + enable + false + true + default + + + + + + + + + + + + runtime; build; native; contentfiles; analyzers; buildtransitive + all + + + runtime; build; native; contentfiles; analyzers; buildtransitive + all + + + + + diff --git a/Datra.Lab.Tests/DescentFixture.cs b/Datra.Lab.Tests/DescentFixture.cs new file mode 100644 index 0000000..65d93cc --- /dev/null +++ b/Datra.Lab.Tests/DescentFixture.cs @@ -0,0 +1,50 @@ +using Datra.Lab.Sample; +using Datra.Lab.Sample.Generated; +using Datra.Providers; + +namespace Datra.Lab.Tests; + +/// +/// The toy game's data staged into a scratch directory, with a lab engine over it. Every test +/// gets its own copy, so the "nothing was written" checks cannot see another test's files. +/// +internal sealed class DescentFixture : IDisposable +{ + public string DataPath { get; } + public string SnapshotPath { get; } + public FileSystemRawDataProvider Provider { get; } + public LabEngine Engine { get; } + + public DescentFixture(Action>? configure = null) + { + var root = Path.Combine(Path.GetTempPath(), "datra-lab-tests", Guid.NewGuid().ToString("N")); + DataPath = DescentData.WriteTo(Path.Combine(root, "data")); + SnapshotPath = Path.Combine(root, "snapshots"); + Provider = new FileSystemRawDataProvider(DataPath); + + var options = new LabOptions(); + DescentLab.Configure(options); + options.SnapshotDirectory(SnapshotPath); + options.Outcomes = DescentPhysics.Bake(LoadSaved()); + configure?.Invoke(options); + + Engine = new LabEngine(Provider, new DescentSim(), options); + } + + /// A context read straight from the staged files: what is actually saved. + public DescentContext LoadSaved() + { + var context = new DescentContext(new FileSystemRawDataProvider(DataPath)); + context.LoadAllAsync().GetAwaiter().GetResult(); + return context; + } + + /// File name → bytes of every staged data file. + public Dictionary ReadFiles() => + Directory.GetFiles(DataPath).ToDictionary(f => Path.GetFileName(f)!, File.ReadAllText); + + public void Dispose() + { + try { Directory.Delete(Path.GetDirectoryName(DataPath)!, recursive: true); } catch { /* best-effort */ } + } +} diff --git a/Datra.Lab.Tests/ForkedContextTests.cs b/Datra.Lab.Tests/ForkedContextTests.cs new file mode 100644 index 0000000..0db87cb --- /dev/null +++ b/Datra.Lab.Tests/ForkedContextTests.cs @@ -0,0 +1,157 @@ +using Datra.Lab.Sample; +using Datra.Lab.Sample.Generated; +using Xunit; + +namespace Datra.Lab.Tests; + +/// +/// A scenario's knobs land in a fork. The saved files, a context loaded from them, and other +/// forks must never see them. +/// +public class ForkedContextTests +{ + private static readonly Dictionary Changes = new() + { + ["EconomyData.StepValue"] = 12, // single data, Set + ["FloorData[B3].Fare"] = 1234, // one row, Set + ["UpgradeData.BaseCost"] = 2, // every row, Scale + ["UpgradeData[carpet].Amount"] = 0.6, // one row of a repeated attribute + ["Floors.ValueGrowth"] = 3, // declared in code + }; + + [Fact] + public async Task Fork_reads_the_knob_values_through_the_ordinary_context_api() + { + using var lab = new DescentFixture(); + + var fork = await lab.Engine.ForkAsync(new Scenario { Changes = Changes }); + + Assert.Equal(12f, fork.Economy.Current!.StepValue); + Assert.Equal(1234, fork.Floor.LoadedItems["B3"].Fare); + Assert.Equal(600, fork.Floor.LoadedItems["B2"].Fare); + Assert.Equal(240f, fork.Upgrade.LoadedItems["push"].BaseCost); + Assert.Equal(180f, fork.Upgrade.LoadedItems["carpet"].BaseCost); + Assert.Equal(0.6f, fork.Upgrade.LoadedItems["carpet"].Amount); + Assert.Equal(0.5f, fork.Upgrade.LoadedItems["box"].Amount); + Assert.Equal(3, DescentData.ValueGrowth(fork), 4); + } + + [Fact] + public async Task Running_a_scenario_leaves_the_saved_files_byte_for_byte() + { + using var lab = new DescentFixture(); + var before = lab.ReadFiles(); + + await lab.Engine.RunAsync(new Scenario { Changes = Changes, Bots = 8 }); + + Assert.Equal(before, lab.ReadFiles()); + Assert.Equal(before.Keys.OrderBy(k => k), Directory.GetFiles(lab.DataPath).Select(Path.GetFileName).OrderBy(k => k)); + } + + [Fact] + public async Task A_context_loaded_from_the_saved_data_does_not_see_the_scenario() + { + using var lab = new DescentFixture(); + + await lab.Engine.RunAsync(new Scenario { Changes = Changes, Bots = 8 }); + var saved = lab.LoadSaved(); + + Assert.Equal(5f, saved.Economy.Current!.StepValue); + Assert.Equal(2000, saved.Floor.LoadedItems["B3"].Fare); + Assert.Equal(120f, saved.Upgrade.LoadedItems["push"].BaseCost); + Assert.Equal(0.25f, saved.Upgrade.LoadedItems["carpet"].Amount); + } + + [Fact] + public async Task Forks_do_not_share_objects_with_each_other() + { + using var lab = new DescentFixture(); + + var changed = await lab.Engine.ForkAsync(new Scenario { Changes = Changes }); + var plain = await lab.Engine.ForkAsync(); + + Assert.NotSame(changed.Floor.LoadedItems["B3"], plain.Floor.LoadedItems["B3"]); + Assert.Equal(2000, plain.Floor.LoadedItems["B3"].Fare); + Assert.Equal(5f, plain.Economy.Current!.StepValue); + } + + [Fact] + public async Task The_baseline_in_the_schema_is_not_moved_by_a_scenario() + { + using var lab = new DescentFixture(); + + await lab.Engine.RunAsync(new Scenario { Changes = Changes, Bots = 8 }); + var schema = await lab.Engine.GetSchemaAsync(); + + Assert.Equal(5, schema.Knobs.Single(k => k.Id == "EconomyData.StepValue").Baseline); + Assert.Equal(2000, schema.Knobs.Single(k => k.Id == "FloorData[B3].Fare").Baseline); + } + + [Fact] + public async Task Saving_a_fork_writes_to_its_overlay_and_not_to_disk() + { + using var lab = new DescentFixture(); + var before = lab.ReadFiles(); + OverlayRawDataProvider? overlay = null; + var forker = new ContextForker(lab.Provider, provider => + { + overlay = (OverlayRawDataProvider)provider; + return new DescentContext(provider); + }); + + var fork = await forker.ForkAsync(); + var floor = fork.Floor.GetWorkingCopy("B1"); + ForkedData.Set(floor, f => f.Fare, 99999); + fork.Floor.MarkAsModified("B1"); + await fork.SaveAllAsync(); + + // The save happened, and it went to the overlay. + Assert.Contains("Floors.yaml", overlay!.WrittenPaths); + Assert.Contains("99999", await overlay.LoadTextAsync("Floors.yaml")); + Assert.Equal(before, lab.ReadFiles()); + Assert.Equal(280, lab.LoadSaved().Floor.LoadedItems["B1"].Fare); + } + + [Fact] + public async Task Overlay_provider_keeps_writes_and_deletes_to_itself() + { + using var lab = new DescentFixture(); + var snapshot = new RawDataSnapshot(lab.Provider); + var overlay = new OverlayRawDataProvider(snapshot); + var other = new OverlayRawDataProvider(snapshot); + var original = await lab.Provider.LoadTextAsync("Economy.yaml"); + + await overlay.SaveTextAsync("Economy.yaml", "StepValue: 99"); + await overlay.SaveTextAsync("New.yaml", "x: 1"); + await overlay.DeleteAsync("Floors.yaml"); + + Assert.Equal("StepValue: 99", await overlay.LoadTextAsync("Economy.yaml")); + Assert.False(overlay.Exists("Floors.yaml")); + await Assert.ThrowsAsync(() => overlay.LoadTextAsync("Floors.yaml")); + + Assert.Equal(original, await other.LoadTextAsync("Economy.yaml")); + Assert.True(other.Exists("Floors.yaml")); + Assert.False(other.Exists("New.yaml")); + + Assert.Equal(original, await lab.Provider.LoadTextAsync("Economy.yaml")); + Assert.False(lab.Provider.Exists("New.yaml")); + Assert.True(lab.Provider.Exists("Floors.yaml")); + } + + [Fact] + public async Task Baseline_is_cached_until_invalidated() + { + using var lab = new DescentFixture(); + var first = await lab.Engine.GetSchemaAsync(); + + File.WriteAllText(Path.Combine(lab.DataPath, "Economy.yaml"), "StepValue: 7\nIntactBonus: 40\nBottlesPerRun: 3\nGlassToughness: 1\n"); + var stale = await lab.Engine.GetSchemaAsync(); + lab.Engine.InvalidateBaseline(); + var fresh = await lab.Engine.GetSchemaAsync(); + + Assert.Equal(5, stale.Knobs.Single(k => k.Id == "EconomyData.StepValue").Baseline); + Assert.Equal(7, fresh.Knobs.Single(k => k.Id == "EconomyData.StepValue").Baseline); + Assert.Equal(first.BaselineHash, stale.BaselineHash); + Assert.NotEqual(first.BaselineHash, fresh.BaselineHash); + } +} diff --git a/Datra.Lab.Tests/KnobSchemaTests.cs b/Datra.Lab.Tests/KnobSchemaTests.cs new file mode 100644 index 0000000..3d546eb --- /dev/null +++ b/Datra.Lab.Tests/KnobSchemaTests.cs @@ -0,0 +1,142 @@ +using Datra.Attributes; +using Xunit; + +namespace Datra.Lab.Tests; + +public class KnobSchemaTests +{ + [Fact] + public async Task Schema_lists_attribute_knobs_with_their_metadata() + { + using var lab = new DescentFixture(); + + var schema = await lab.Engine.GetSchemaAsync(); + + var step = schema.Knobs.Single(k => k.Id == "EconomyData.StepValue"); + Assert.Equal("Step value", step.Label); + Assert.Equal("Rewards", step.Group); + Assert.Equal("coins/step", step.Unit); + Assert.Equal(1, step.Min); + Assert.Equal(15, step.Max); + Assert.Equal(0.5, step.Step); + Assert.Equal(KnobLayer.Economy, step.Layer); + Assert.Equal(KnobApply.Set, step.Apply); + Assert.Equal(5, step.Baseline); + Assert.False(step.Integer); + Assert.True(step.Editable); + Assert.Equal("EconomyData", step.Source!.DataType); + Assert.Equal("StepValue", step.Source.Property); + Assert.Null(step.Source.Row); + Assert.Equal("Economy.yaml", step.Source.File); + } + + [Fact] + public async Task EachRow_expands_into_one_knob_per_row_in_file_order() + { + using var lab = new DescentFixture(); + + var schema = await lab.Engine.GetSchemaAsync(); + + var fares = schema.Knobs.Where(k => k.Source?.Property == "Fare").ToList(); + Assert.Equal(new[] { "B1", "B2", "B3", "B4", "B5" }, fares.Select(k => k.Source!.Row)); + Assert.Equal("FloorData[B3].Fare", fares[2].Id); + Assert.Equal("Fare · B3", fares[2].Label); + Assert.Equal(2000, fares[2].Baseline); + Assert.True(fares[2].Integer); + // No range on the attribute: each row gets one around its own value. + Assert.Equal(0, fares[2].Min); + Assert.Equal(4000, fares[2].Max); + Assert.Equal(64000, fares[4].Max); + } + + [Fact] + public async Task Row_knob_addresses_a_single_row_and_the_attribute_can_repeat() + { + using var lab = new DescentFixture(); + + var schema = await lab.Engine.GetSchemaAsync(); + + var carpet = schema.Knobs.Single(k => k.Id == "UpgradeData[carpet].Amount"); + Assert.Equal("Carpet value per level", carpet.Label); + Assert.Equal(0.25, carpet.Baseline, 6); + Assert.Equal("carpet", carpet.Source!.Row); + + var push = schema.Knobs.Single(k => k.Id == "UpgradeData[push].Amount"); + Assert.Equal(0.35, push.Baseline, 6); + } + + [Fact] + public async Task Scale_knob_over_all_rows_rests_at_one() + { + using var lab = new DescentFixture(); + + var schema = await lab.Engine.GetSchemaAsync(); + + var prices = schema.Knobs.Single(k => k.Id == "UpgradeData.BaseCost"); + Assert.Equal(KnobApply.Scale, prices.Apply); + Assert.Equal(1, prices.Baseline); + Assert.Null(prices.Source!.Row); + } + + [Fact] + public async Task Physics_knobs_are_listed_but_not_editable() + { + using var lab = new DescentFixture(); + + var schema = await lab.Engine.GetSchemaAsync(); + + var glass = schema.Knobs.Single(k => k.Id == "EconomyData.GlassToughness"); + Assert.Equal(KnobLayer.Physics, glass.Layer); + Assert.False(glass.Editable); + + var error = await Assert.ThrowsAsync(() => lab.Engine.RunAsync( + new Scenario { Changes = { ["EconomyData.GlassToughness"] = 1.5 } })); + Assert.Contains("physics", error.Message); + } + + [Fact] + public async Task Declared_knob_reads_its_baseline_from_the_data() + { + using var lab = new DescentFixture(); + + var schema = await lab.Engine.GetSchemaAsync(); + + var growth = schema.Knobs.Single(k => k.Id == "Floors.ValueGrowth"); + Assert.Equal("Depth value growth", growth.Label); + Assert.Null(growth.Source); + Assert.Equal(Math.Pow(18, 0.25), growth.Baseline, 6); + // Declared knobs come before attribute knobs. + Assert.Equal(0, schema.Knobs.IndexOf(growth)); + } + + [Fact] + public async Task Schema_carries_policies_parameters_checks_and_defaults() + { + using var lab = new DescentFixture(); + + var schema = await lab.Engine.GetSchemaAsync(); + + Assert.Equal(new[] { "efficient", "cheap", "random" }, schema.Policies.Select(p => p.Id)); + Assert.Equal("efficient", schema.Defaults.Policy); + Assert.Equal(40, schema.Defaults.Bots); + Assert.Equal(400, schema.Defaults.MaxBots); + var shop = Assert.Single(schema.PolicyParams); + Assert.Equal("shopSeconds", shop.Id); + Assert.Equal(8, shop.Default); + Assert.Equal(new[] { "First purchase", "Longest run" }, schema.Checks.Select(c => c.Name)); + Assert.True(schema.Snapshots); + Assert.Equal("toy-1", schema.OutcomeVersion); + Assert.Equal(64, schema.BaselineHash.Length); + } + + [Fact] + public async Task Unknown_knob_in_a_scenario_is_rejected_by_name() + { + using var lab = new DescentFixture(); + + var error = await Assert.ThrowsAsync(() => lab.Engine.RunAsync( + new Scenario { Changes = { ["EconomyData.Nope"] = 1 } })); + + Assert.Contains("EconomyData.Nope", error.Message); + } +} diff --git a/Datra.Lab.Tests/SimRunTests.cs b/Datra.Lab.Tests/SimRunTests.cs new file mode 100644 index 0000000..3b8deac --- /dev/null +++ b/Datra.Lab.Tests/SimRunTests.cs @@ -0,0 +1,308 @@ +using Datra.Lab.Sample.Generated; +using Datra.Providers; +using Xunit; + +namespace Datra.Lab.Tests; + +/// The record contract: what a simulator writes and what the aggregator makes of it. +public class SimRunTests +{ + private static readonly DescentContext NoData = new(new FileSystemRawDataProvider(".")); + + private sealed class Script : ISimulator + { + private readonly Action _play; + public Script(Action play) => _play = play; + public void Play(DescentContext data, SimRun run) => _play(run); + } + + private static IReadOnlyList Run(Action play, int bots = 1, IOutcomeReader? outcomes = null) => + BotRunner.Run(new Script(play), NoData, new RunSettings { Bots = bots }, outcomes); + + [Fact] + public void Stages_ticks_purchases_and_marks_are_recorded_against_game_time() + { + var record = Run(run => + { + run.Stage("A", targetSeconds: 60, label: "First"); + run.Tick(20, earned: 10); + run.Purchase("hat", 5, group: "Account", label: "Hat Lv1"); + run.Tick(10, earned: 0, kind: "shop"); + run.Mark("first hat"); + run.Stage("B"); + run.Tick(40, earned: 30); + })[0]; + + Assert.True(record.Finished); + Assert.Equal(70, record.TotalSeconds); + Assert.Equal(40, record.TotalEarned); + + Assert.Equal(new[] { "A", "B" }, record.Stages.Select(s => s.Id)); + Assert.Equal("First", record.Stages[0].Label); + Assert.Equal(60, record.Stages[0].TargetSeconds); + Assert.Equal((0d, 30d), (record.Stages[0].StartSeconds, record.Stages[0].EndSeconds!.Value)); + Assert.Equal((30d, 70d), (record.Stages[1].StartSeconds, record.Stages[1].EndSeconds!.Value)); + + var purchase = Assert.Single(record.Purchases); + Assert.Equal((20d, "hat", "Hat Lv1", 5d, "Account", 0), + (purchase.Time, purchase.Id, purchase.Label, purchase.Cost, purchase.Group, purchase.Stage)); + Assert.Equal(20, record.FirstPurchaseSeconds); + + var mark = Assert.Single(record.Marks); + Assert.Equal((30d, "first hat", 0), (mark.Time, mark.Name, mark.Stage)); + + Assert.Equal(new[] { "run", "shop", "run" }, record.Ticks.Select(t => t.Kind)); + Assert.Equal(40, record.LongestTickSeconds("run")); + Assert.Equal(10, record.LongestTickSeconds("shop")); + } + + [Fact] + public void Entering_the_stage_the_bot_is_already_in_does_nothing() + { + var record = Run(run => + { + run.Stage("A"); + run.Tick(10); + run.Stage("A"); + run.Tick(10); + })[0]; + + var stage = Assert.Single(record.Stages); + Assert.Equal(20, stage.EndSeconds); + } + + [Fact] + public void Progress_can_fall_when_spending_sets_the_bot_back() + { + var records = Run(run => + { + run.Stage("A"); + run.Tick(10, 60); + run.Progress(0.6); + run.Purchase("x", 40); + run.Progress(0.2); // the wallet is the fare box + run.Tick(10, 80); + run.Progress(1); + run.Stage("B"); + run.Tick(20, 0); + }); + var result = ResultAggregator.Aggregate(records); + + double DepthAt(double t) => result.Progression.Points.Last(p => p.T <= t + 1e-9).Median; + + Assert.Equal(40, result.Progression.TMax); + Assert.Equal(ResultAggregator.ProgressionSamples + 1, result.Progression.Points.Count); + Assert.Equal(0, DepthAt(5)); + Assert.Equal(0.2, DepthAt(15), 6); // after the purchase, below where it was + Assert.Equal(1, DepthAt(25), 6); // in stage B, nothing done yet + Assert.Equal(2, DepthAt(40), 6); // finished: past the last stage + } + + [Fact] + public void Stage_times_are_the_median_across_bots_with_a_p10_p90_range() + { + var records = Run(run => + { + run.Stage("A", targetSeconds: 100); + run.Tick(100 + run.Bot * 10); // bots 0..10 take 100..200 s + run.Stage("B"); + run.Tick(50); + }, bots: 11); + var result = ResultAggregator.Aggregate(records); + + var a = result.Stages[0]; + Assert.Equal((11, 11), (a.Reached, a.Completed)); + Assert.Equal(150, a.Median); + Assert.Equal(110, a.P10); + Assert.Equal(190, a.P90); + Assert.Equal(100, a.TargetSeconds); + Assert.Equal(200, result.Total!.Median); + Assert.Equal(11, result.Finished); + + // The representative bot is the one closest to the median total. + Assert.Equal(5, result.Purchases.Bot); + Assert.Equal(new[] { 150d, 200d }, result.Purchases.StageEnds.Select(s => s.T)); + } + + [Fact] + public void Purchase_timeline_is_the_representative_bots_with_medians_across_all() + { + var records = Run(run => + { + run.Stage("A"); + run.Tick(10 + run.Bot); + run.Purchase("a", 10, "Account"); + run.Tick(10); + if (run.Bot % 2 == 0) run.Purchase("b", 20, "Floor device"); + }, bots: 5); + var result = ResultAggregator.Aggregate(records); + + Assert.Equal(12, result.Purchases.FirstSeconds); + Assert.Equal(2, result.Purchases.CountMedian); + Assert.Equal(2, result.Purchases.Bot); + Assert.Equal(new[] { "Account", "Floor device" }, result.Purchases.Groups); + Assert.Equal(new[] { "a", "b" }, result.Purchases.Items.Select(i => i.Id)); + Assert.Equal("A", result.Purchases.Items[0].Stage); + } + + [Fact] + public void Checks_report_the_median_against_the_target() + { + var records = Run(run => + { + run.Stage("A"); + run.Tick(30 + run.Bot * 30); + if (run.Bot < 4) run.Purchase("a", 1); + }, bots: 5); + + var result = ResultAggregator.Aggregate(records, new[] + { + new LabCheck("First purchase", r => r.FirstPurchaseSeconds, "<= 60", "s"), + new LabCheck("Longest run", r => r.LongestTickSeconds("run"), "< 90", "s"), + new LabCheck("Never", r => double.NaN, ">= 1"), + }); + + // Bot 4 never bought: it has no value and is left out rather than counted as zero. + Assert.Equal((75d, false), (result.Checks[0].Value!.Value, result.Checks[0].Ok!.Value)); + Assert.Equal("<= 60", result.Checks[0].Target); + Assert.Equal((90d, false), (result.Checks[1].Value!.Value, result.Checks[1].Ok!.Value)); + Assert.Null(result.Checks[2].Value); + Assert.Null(result.Checks[2].Ok); + Assert.Throws(() => new LabCheck("bad", r => 0, "about 5")); + } + + [Fact] + public void Explanations_and_marks_are_counted_per_bot() + { + var records = Run(run => + { + run.Stage("A"); + run.Tick(10); + run.Stage("B"); + run.Tick(10 + run.Bot); + if (run.Bot > 0) run.Mark("late"); + run.Explain("B", "slow stairs"); + run.Explain("B", "slow stairs"); + if (run.Bot == 0) run.Explain("A", "cold start"); + }, bots: 3); + var result = ResultAggregator.Aggregate(records); + + Assert.Equal(new[] { ("A", "cold start", 1), ("B", "slow stairs", 3) }, + result.Explains.Select(e => (e.Stage, e.Text, e.Bots))); + var mark = Assert.Single(result.Marks); + Assert.Equal(("late", 2, 21.5), (mark.Name, mark.Bots, mark.FirstSeconds)); + } + + [Fact] + public void Outcome_draws_from_the_stored_pool_with_the_bots_own_randomness() + { + var key = PhysicsKey.Of(("floor", "B1"), ("push", 2)); + var outcomes = new InMemoryOutcomes("v1").Add(key, Enumerable.Range(0, 50)); + var drawn = new List[2]; + + for (var pass = 0; pass < 2; pass++) + { + var seen = new List(); + Run(run => { for (var i = 0; i < 20; i++) seen.Add(run.Outcome(key)); }, outcomes: outcomes); + drawn[pass] = seen; + } + + Assert.Equal(drawn[0], drawn[1]); + Assert.True(drawn[0].Distinct().Count() > 5); + Assert.All(drawn[0], v => Assert.InRange(v, 0, 49)); + } + + [Fact] + public void A_missing_physics_key_stops_that_bot_and_is_named_in_the_result() + { + var known = PhysicsKey.Of(("floor", "B1")); + var unknown = PhysicsKey.Of(("floor", "B9")); + var outcomes = new InMemoryOutcomes().Add(known, new[] { 1 }); + + var records = Run(run => + { + run.Stage("A"); + run.Tick(10, run.Outcome(known)); + if (run.Bot == 1) run.Outcome(unknown); + run.Tick(10); + }, bots: 2, outcomes: outcomes); + var result = ResultAggregator.Aggregate(records); + + Assert.True(records[0].Finished); + Assert.False(records[1].Finished); + Assert.Equal(new[] { "floor=B9" }, records[1].MissingOutcomes); + Assert.Contains(result.Problems, p => p.Kind == "missingOutcome" && p.Message == "floor=B9" && p.Bots == 1); + Assert.Contains(result.Problems, p => p.Kind == "error" && p.Bots == 1); + Assert.Equal(1, result.Finished); + } + + [Fact] + public void TryOutcome_lets_the_simulator_fall_back_but_still_reports_the_key() + { + var records = Run(run => + { + run.Stage("A"); + var found = run.TryOutcome(PhysicsKey.Of(("floor", "B9")), out var value); + run.Tick(10, found ? value : 3); + }); + + Assert.True(records[0].Finished); + Assert.Equal(3, records[0].TotalEarned); + Assert.Equal(new[] { "floor=B9" }, records[0].MissingOutcomes); + } + + [Fact] + public void Physics_key_is_the_same_whatever_order_its_parts_are_given_in() + { + var a = PhysicsKey.Of(("push", 2), ("floor", "B1"), ("scale", 1.5)); + var b = PhysicsKey.Of(("floor", "B1"), ("scale", 1.5), ("push", 2)); + + Assert.Equal("floor=B1;push=2;scale=1.5", a.Text); + Assert.Equal(a, b); + Assert.Equal(a.Hash("v1"), b.Hash("v1")); + Assert.NotEqual(a.Hash("v1"), a.Hash("v2")); + Assert.Equal(a, PhysicsKey.Parse(a.Text)); + } + + [Fact] + public void Jsonl_reader_loads_one_pool_per_key_file() + { + var directory = Path.Combine(Path.GetTempPath(), "datra-lab-tests", Guid.NewGuid().ToString("N")); + Directory.CreateDirectory(directory); + try + { + var reader = new JsonlOutcomeReader(directory, "pin-7"); + var key = PhysicsKey.Of(("floor", "B1"), ("push", 0)); + File.WriteAllLines(reader.PathFor(key), new[] + { + """{"steps":3,"intact":false,"seconds":5.4}""", + "", + """{"steps":8,"intact":true,"seconds":9.4}""", + }); + + var pool = reader.Pool(key); + + Assert.Equal("pin-7", reader.Version); + Assert.Equal(new[] { 3, 8 }, pool!.Select(o => o.Steps)); + Assert.True(pool![1].Intact); + Assert.Null(reader.Pool(PhysicsKey.Of(("floor", "B2")))); + } + finally + { + Directory.Delete(directory, recursive: true); + } + } + + [Fact] + public void SimRandom_is_a_fixed_sequence_per_seed() + { + var a = new SimRandom(42); + var b = new SimRandom(42); + var first = Enumerable.Range(0, 5).Select(_ => a.NextULong()).ToList(); + + Assert.Equal(first, Enumerable.Range(0, 5).Select(_ => b.NextULong())); + // Pinned: a change to the generator would silently change every stored result. + Assert.Equal(13679457532755275413UL, first[0]); + Assert.All(Enumerable.Range(0, 1000).Select(_ => a.NextDouble()), v => Assert.InRange(v, 0, 0.9999999999999999)); + } +} diff --git a/Datra.Lab.Tests/SnapshotTests.cs b/Datra.Lab.Tests/SnapshotTests.cs new file mode 100644 index 0000000..73946b1 --- /dev/null +++ b/Datra.Lab.Tests/SnapshotTests.cs @@ -0,0 +1,85 @@ +using Xunit; + +namespace Datra.Lab.Tests; + +public class SnapshotTests +{ + [Fact] + public async Task Snapshot_round_trips_the_scenario_and_the_result_it_gave() + { + using var lab = new DescentFixture(); + var scenario = new Scenario + { + Changes = { ["EconomyData.StepValue"] = 9, ["FloorData[B3].Fare"] = 1500 }, + Policy = "cheap", + Bots = 16, + Seed = 4, + }; + + var saved = await lab.Engine.SaveSnapshotAsync("cheap fares v2", scenario); + var loaded = await lab.Engine.Snapshots!.LoadAsync("cheap fares v2"); + + Assert.NotNull(loaded); + Assert.Equal("cheap fares v2", loaded!.Name); + Assert.Equal(saved.BaselineHash, loaded.BaselineHash); + Assert.Equal(9, loaded.Scenario.Changes["EconomyData.StepValue"]); + Assert.Equal(1500, loaded.Scenario.Changes["FloorData[B3].Fare"]); + Assert.Equal(("cheap", 16, 4), (loaded.Scenario.Policy, loaded.Scenario.Bots, loaded.Scenario.Seed)); + Assert.Equal(LabJson.Serialize(saved.Result), LabJson.Serialize(loaded.Result)); + Assert.Equal(5, loaded.Result.Stages.Count); + } + + [Fact] + public async Task A_loaded_scenario_reproduces_the_stored_result() + { + using var lab = new DescentFixture(); + await lab.Engine.SaveSnapshotAsync("v1", new Scenario { Changes = { ["UpgradeData.BaseCost"] = 1.5 } }); + + var loaded = await lab.Engine.Snapshots!.LoadAsync("v1"); + var again = await lab.Engine.RunAsync(loaded!.Scenario); + + Assert.Equal(loaded.Result.Total!.Median, again.Total!.Median); + Assert.Equal(loaded.Result.Stages.Select(s => s.Median), again.Stages.Select(s => s.Median)); + } + + [Fact] + public async Task Snapshots_are_listed_newest_first_as_plain_json_files() + { + using var lab = new DescentFixture(); + await lab.Engine.SaveSnapshotAsync("first", new Scenario()); + await Task.Delay(20); + await lab.Engine.SaveSnapshotAsync("second", new Scenario { Changes = { ["EconomyData.StepValue"] = 6 } }); + + var list = await lab.Engine.Snapshots!.ListAsync(); + + Assert.Equal(new[] { "second", "first" }, list.Select(s => s.Name)); + Assert.Equal(new[] { 1, 0 }, list.Select(s => s.ChangedKnobs)); + Assert.True(File.Exists(Path.Combine(lab.SnapshotPath, "second.json"))); + Assert.Contains("\"EconomyData.StepValue\": 6", File.ReadAllText(Path.Combine(lab.SnapshotPath, "second.json"))); + } + + [Theory] + [InlineData("../escape")] + [InlineData("a/b")] + [InlineData("")] + [InlineData(".hidden")] + [InlineData("trailing.")] + [InlineData("a..b")] + public async Task Names_that_could_leave_the_snapshot_directory_are_refused(string name) + { + using var lab = new DescentFixture(); + + await Assert.ThrowsAsync(() => lab.Engine.SaveSnapshotAsync(name, new Scenario())); + await Assert.ThrowsAsync(() => lab.Engine.Snapshots!.LoadAsync(name)); + Assert.False(Directory.Exists(lab.SnapshotPath) && Directory.GetFiles(lab.SnapshotPath).Length > 0); + } + + [Fact] + public async Task A_missing_snapshot_loads_as_null() + { + using var lab = new DescentFixture(); + + Assert.Null(await lab.Engine.Snapshots!.LoadAsync("nothing here")); + Assert.Empty(await lab.Engine.Snapshots.ListAsync()); + } +} diff --git a/Datra.Lab/Context/ContextForker.cs b/Datra.Lab/Context/ContextForker.cs new file mode 100644 index 0000000..717fa7a --- /dev/null +++ b/Datra.Lab/Context/ContextForker.cs @@ -0,0 +1,77 @@ +#nullable enable +using System; +using System.Linq; +using System.Reflection; +using System.Threading.Tasks; +using Datra.Interfaces; + +namespace Datra.Lab +{ + /// + /// Makes independent, loaded copies of a data context. A fork is an ordinary + /// , so a simulator reads data.Bottle the way game + /// code does, but it lives on an : its objects are its + /// own and nothing it does reaches the saved data. + /// + public sealed class ContextForker where TContext : class, IDataContext + { + private readonly RawDataSnapshot _snapshot; + private readonly Func _create; + + /// Where the baseline data is read from. Only ever read. + /// + /// Builds a context on a given provider. Defaults to the generated constructor + /// new TContext(IRawDataProvider, ...optional...). + /// + public ContextForker(IRawDataProvider source, Func? create = null) + { + _snapshot = new RawDataSnapshot(source ?? throw new ArgumentNullException(nameof(source))); + _create = create ?? DefaultFactory(); + } + + /// The cached baseline files. Shared by every fork. + public RawDataSnapshot Snapshot => _snapshot; + + /// A freshly loaded context holding the baseline values. + public async Task ForkAsync() + { + var context = _create(new OverlayRawDataProvider(_snapshot)) + ?? throw new InvalidOperationException("The context factory returned null."); + await context.LoadAllAsync().ConfigureAwait(false); + return context; + } + + /// Drop the cached baseline so the next fork re-reads the source (after a save or reload). + public void Invalidate() => _snapshot.Clear(); + + private static Func DefaultFactory() + { + // The source generator emits (IRawDataProvider, DataSerializerFactory = null, + // DatraConfigurationValue = null, ISerializationLogger = null). Any constructor whose + // first parameter takes the provider and whose remaining ones are optional will do. + var constructor = typeof(TContext) + .GetConstructors(BindingFlags.Public | BindingFlags.Instance) + .Select(c => new { Constructor = c, Parameters = c.GetParameters() }) + .Where(c => c.Parameters.Length > 0 + && c.Parameters[0].ParameterType.IsAssignableFrom(typeof(OverlayRawDataProvider)) + && c.Parameters.Skip(1).All(p => p.HasDefaultValue)) + .OrderBy(c => c.Parameters.Length) + .FirstOrDefault(); + + if (constructor is null) + { + throw new InvalidOperationException( + $"{typeof(TContext).Name} has no public constructor of the shape (IRawDataProvider, ...optional). " + + "Pass a context factory (LabOptions.CreateContext) instead."); + } + + return provider => + { + var arguments = constructor.Parameters + .Select((p, i) => i == 0 ? (object?)provider : p.DefaultValue) + .ToArray(); + return (TContext)constructor.Constructor.Invoke(arguments); + }; + } + } +} diff --git a/Datra.Lab/Context/OverlayRawDataProvider.cs b/Datra.Lab/Context/OverlayRawDataProvider.cs new file mode 100644 index 0000000..a42bb2d --- /dev/null +++ b/Datra.Lab/Context/OverlayRawDataProvider.cs @@ -0,0 +1,75 @@ +#nullable enable +using System; +using System.Collections.Concurrent; +using System.Collections.Generic; +using System.IO; +using System.Linq; +using System.Threading.Tasks; +using Datra.Attributes; +using Datra.Interfaces; + +namespace Datra.Lab +{ + /// + /// The raw data provider a forked context runs on. Reads fall through to the shared + /// baseline snapshot; writes and deletes stay in this overlay and never reach the source, + /// so nothing a simulator (or a stray SaveAllAsync) does can change saved data. + /// + public sealed class OverlayRawDataProvider : IFormatAwareRawDataProvider + { + private readonly RawDataSnapshot _baseline; + // A null value is a tombstone: the file was deleted in this overlay. + private readonly ConcurrentDictionary _writes = + new ConcurrentDictionary(StringComparer.Ordinal); + + public OverlayRawDataProvider(RawDataSnapshot baseline) + { + _baseline = baseline ?? throw new ArgumentNullException(nameof(baseline)); + } + + /// Paths written in this overlay (deleted ones excluded). + public IReadOnlyCollection WrittenPaths => + _writes.Where(p => p.Value != null).Select(p => p.Key).ToList(); + + public async Task LoadTextAsync(string path) + { + var text = _writes.TryGetValue(path, out var written) + ? written + : await _baseline.LoadTextAsync(path).ConfigureAwait(false); + return text ?? throw new FileNotFoundException($"File not found: {path}", path); + } + + public Task SaveTextAsync(string path, string content) + { + _writes[path] = content; + return Task.CompletedTask; + } + + public bool Exists(string path) => + _writes.TryGetValue(path, out var written) ? written != null : _baseline.Exists(path); + + public string ResolveFilePath(string path) => "overlay://" + path.Replace('\\', '/'); + + public async Task> LoadMultipleTextAsync(string folderPathOrLabel, string pattern = "*.json") + { + var files = await _baseline.LoadFolderAsync(folderPathOrLabel, pattern).ConfigureAwait(false); + // Copy: the caller owns the dictionary it gets, the snapshot keeps its own. + return new Dictionary(files, StringComparer.Ordinal); + } + + public async Task> ListFilesAsync(string folderPathOrLabel, string pattern = "*.json") + { + var files = await _baseline.LoadFolderAsync(folderPathOrLabel, pattern).ConfigureAwait(false); + return files.Keys.ToList(); + } + + public Task DeleteAsync(string path) + { + var existed = Exists(path); + _writes[path] = null; + return Task.FromResult(existed); + } + + public DataFormat? GetFormat(string path) => _baseline.GetFormat(path); + } +} diff --git a/Datra.Lab/Context/RawDataSnapshot.cs b/Datra.Lab/Context/RawDataSnapshot.cs new file mode 100644 index 0000000..f557f5d --- /dev/null +++ b/Datra.Lab/Context/RawDataSnapshot.cs @@ -0,0 +1,98 @@ +#nullable enable +using System; +using System.Collections.Concurrent; +using System.Collections.Generic; +using System.IO; +using System.Linq; +using System.Security.Cryptography; +using System.Text; +using System.Threading.Tasks; +using Datra.Attributes; +using Datra.Interfaces; + +namespace Datra.Lab +{ + /// + /// A read-through cache of the raw files behind the baseline data. Every fork reads from + /// here, so a scenario run parses text from memory instead of going back to the source + /// provider. Nothing is ever written to the source. + /// + public sealed class RawDataSnapshot + { + private readonly IRawDataProvider _source; + private readonly ConcurrentDictionary _texts = + new ConcurrentDictionary(StringComparer.Ordinal); + private readonly ConcurrentDictionary> _folders = + new ConcurrentDictionary>(StringComparer.Ordinal); + + public RawDataSnapshot(IRawDataProvider source) + { + _source = source ?? throw new ArgumentNullException(nameof(source)); + } + + /// The text at , or null when the source has no such file. + public async Task LoadTextAsync(string path) + { + if (_texts.TryGetValue(path, out var cached)) return cached; + + string? text; + try + { + text = await _source.LoadTextAsync(path).ConfigureAwait(false); + } + catch (FileNotFoundException) + { + text = null; + } + + return _texts.GetOrAdd(path, text); + } + + public bool Exists(string path) => + _texts.TryGetValue(path, out var cached) ? cached != null : _source.Exists(path); + + public async Task> LoadFolderAsync(string folderPathOrLabel, string pattern) + { + var cacheKey = folderPathOrLabel + "\n" + pattern; + if (_folders.TryGetValue(cacheKey, out var cached)) return cached; + + var files = await _source.LoadMultipleTextAsync(folderPathOrLabel, pattern).ConfigureAwait(false); + return _folders.GetOrAdd(cacheKey, files); + } + + public DataFormat? GetFormat(string path) => + _source is IFormatAwareRawDataProvider aware ? aware.GetFormat(path) : null; + + /// Forget everything read so far. The next fork re-reads the source. + public void Clear() + { + _texts.Clear(); + _folders.Clear(); + } + + /// + /// SHA-256 over every file read so far (path and content, ordered by path). Identifies + /// the baseline a result was computed from. + /// + public string ComputeHash() + { + var builder = new StringBuilder(); + foreach (var pair in _texts.OrderBy(p => p.Key, StringComparer.Ordinal)) + { + if (pair.Value is null) continue; + builder.Append(pair.Key).Append('\n').Append(pair.Value.Length).Append('\n').Append(pair.Value).Append('\n'); + } + foreach (var folder in _folders.OrderBy(p => p.Key, StringComparer.Ordinal)) + { + foreach (var file in folder.Value.OrderBy(p => p.Key, StringComparer.Ordinal)) + builder.Append(folder.Key).Append('/').Append(file.Key).Append('\n').Append(file.Value).Append('\n'); + } + + using var sha = SHA256.Create(); + var hash = sha.ComputeHash(Encoding.UTF8.GetBytes(builder.ToString())); + var hex = new StringBuilder(hash.Length * 2); + foreach (var b in hash) hex.Append(b.ToString("x2")); + return hex.ToString(); + } + } +} diff --git a/Datra.Lab/Datra.Lab.csproj b/Datra.Lab/Datra.Lab.csproj new file mode 100644 index 0000000..763e54c --- /dev/null +++ b/Datra.Lab/Datra.Lab.csproj @@ -0,0 +1,20 @@ + + + + + netstandard2.1 + latest + enable + Datra.Lab + Datra.Lab + true + Datra.Lab + Balance lab for Datra-managed game data: knob schema, forked data contexts, a simulator contract, a seeded bot runner and result aggregation. No UI. + datra;game;data;balance;simulation + + + + + + + diff --git a/Datra.Lab/Knobs/ForkedData.cs b/Datra.Lab/Knobs/ForkedData.cs new file mode 100644 index 0000000..f18540f --- /dev/null +++ b/Datra.Lab/Knobs/ForkedData.cs @@ -0,0 +1,31 @@ +#nullable enable +using System; +using System.Linq.Expressions; +using System.Reflection; + +namespace Datra.Lab +{ + /// + /// Writes to data objects of a forked context. Datra's analyzer (DATRA001) rejects plain + /// assignments to data classes because loaded game data is meant to be read-only; a knob's + /// write is the one place that has to change it, and only ever on a fork. + /// + public static class ForkedData + { + /// + /// Set of to . + /// + /// ForkedData.Set(floor, f => f.Fare, 1200); + public static void Set(TData target, Expression> property, TValue value) + where TData : class + { + if (target is null) throw new ArgumentNullException(nameof(target)); + if (property is null) throw new ArgumentNullException(nameof(property)); + + if (!(property.Body is MemberExpression member) || !(member.Member is PropertyInfo info) || !info.CanWrite) + throw new ArgumentException("Expected a writable property, as in f => f.Fare.", nameof(property)); + + info.SetValue(target, value); + } + } +} diff --git a/Datra.Lab/Knobs/KnobBuilder.cs b/Datra.Lab/Knobs/KnobBuilder.cs new file mode 100644 index 0000000..b2f9d91 --- /dev/null +++ b/Datra.Lab/Knobs/KnobBuilder.cs @@ -0,0 +1,84 @@ +#nullable enable +using System; +using System.Collections.Generic; +using Datra.Attributes; +using Datra.Interfaces; + +namespace Datra.Lab +{ + /// + /// A group of knobs declared in code, for values an attribute cannot express: one knob that + /// rewrites several fields (a fare curve, a price multiplier over a whole table). + /// + public interface IKnobSet where TContext : class, IDataContext + { + void Declare(KnobBuilder knobs); + } + + /// Collects knobs declared in code. See . + public sealed class KnobBuilder where TContext : class, IDataContext + { + internal List> Knobs { get; } = new List>(); + + /// + /// Declare a knob by how to read its value from a context and how to write one back. + /// + /// Name shown on the knob. + /// The knob's value in the given data. Called once on the baseline. + /// Applies a value to a forked context. Never called on the baseline. + /// Stable id. Defaults to a slug of . + public KnobBuilder Add( + string label, + Func read, + Action write, + double min, + double max, + double step = 0, + string group = "", + string unit = "", + string hint = "", + KnobLayer layer = KnobLayer.Economy, + string? id = null) + { + if (string.IsNullOrWhiteSpace(label)) throw new ArgumentException("A knob needs a label.", nameof(label)); + if (read is null) throw new ArgumentNullException(nameof(read)); + if (write is null) throw new ArgumentNullException(nameof(write)); + if (!(max > min)) throw new ArgumentException($"Knob '{label}': max must be greater than min."); + + Knobs.Add(new DeclaredKnob( + id ?? "knob:" + Slug(label), label, group, unit, hint, min, max, step, layer, read, write)); + return this; + } + + private static string Slug(string label) + { + var chars = new char[label.Length]; + for (var i = 0; i < label.Length; i++) + chars[i] = char.IsLetterOrDigit(label[i]) ? char.ToLowerInvariant(label[i]) : '-'; + return new string(chars).Trim('-'); + } + } + + internal sealed class DeclaredKnob where TContext : class, IDataContext + { + public DeclaredKnob(string id, string label, string group, string unit, string hint, + double min, double max, double step, KnobLayer layer, + Func read, Action write) + { + Id = id; Label = label; Group = group; Unit = unit; Hint = hint; + Min = min; Max = max; Step = step; Layer = layer; Read = read; Write = write; + } + + public string Id { get; } + public string Label { get; } + public string Group { get; } + public string Unit { get; } + public string Hint { get; } + public double Min { get; } + public double Max { get; } + public double Step { get; } + public KnobLayer Layer { get; } + public Func Read { get; } + public Action Write { get; } + } +} diff --git a/Datra.Lab/Knobs/KnobInfo.cs b/Datra.Lab/Knobs/KnobInfo.cs new file mode 100644 index 0000000..092cace --- /dev/null +++ b/Datra.Lab/Knobs/KnobInfo.cs @@ -0,0 +1,55 @@ +#nullable enable +using Datra.Attributes; + +namespace Datra.Lab +{ + /// + /// A knob as a tool sees it: identity, presentation, range and the value it rests at in + /// the baseline data. Serialised as part of . + /// + public sealed class KnobInfo + { + /// Stable id, e.g. Economy.StepValue or Floors[B3].Fare. + public string Id { get; set; } = string.Empty; + public string Label { get; set; } = string.Empty; + public string Group { get; set; } = string.Empty; + public string Unit { get; set; } = string.Empty; + public string Hint { get; set; } = string.Empty; + public double Min { get; set; } + public double Max { get; set; } + public double Step { get; set; } + public KnobLayer Layer { get; set; } + public KnobApply Apply { get; set; } + + /// The value the knob has when the scenario does not mention it. + public double Baseline { get; set; } + + /// The field behind the knob holds whole numbers. + public bool Integer { get; set; } + + /// + /// A knob over several rows that do not share one value: + /// moving it overwrites the per-row differences. + /// + public bool Mixed { get; set; } + + /// False for knobs the tool shows but does not let a scenario change yet (physics in P0). + public bool Editable { get; set; } = true; + + /// Where the value lives in the data. Null for knobs declared in code. + public KnobSource? Source { get; set; } + } + + /// The table field a knob writes to. + public sealed class KnobSource + { + public string DataType { get; set; } = string.Empty; + public string Property { get; set; } = string.Empty; + + /// The row Id, or null when the knob covers every row (or the data is single). + public string? Row { get; set; } + + /// The data file, as declared on [TableData] / [SingleData]. + public string File { get; set; } = string.Empty; + } +} diff --git a/Datra.Lab/Knobs/KnobSchemaReader.cs b/Datra.Lab/Knobs/KnobSchemaReader.cs new file mode 100644 index 0000000..3b9e9fd --- /dev/null +++ b/Datra.Lab/Knobs/KnobSchemaReader.cs @@ -0,0 +1,344 @@ +#nullable enable +using System; +using System.Collections; +using System.Collections.Generic; +using System.Globalization; +using System.Linq; +using System.Reflection; +using Datra.Attributes; +using Datra.Interfaces; + +namespace Datra.Lab +{ + /// + /// One knob bound to a context type: its description plus the code that writes a value + /// into a (forked) context. + /// + public sealed class KnobBinding where TContext : class, IDataContext + { + private readonly Action _apply; + + internal KnobBinding(KnobInfo info, int order, Action apply) + { + Info = info; + Order = order; + _apply = apply; + } + + public KnobInfo Info { get; } + + /// Position in the schema. Knobs are applied in this order within one pass. + internal int Order { get; } + + /// Write into . + public void Apply(TContext data, double value) => _apply(data, value); + } + + /// + /// Builds the knob list for a context by reflection: every on + /// the properties of the context's data types, plus knobs declared in code. + /// + public static class KnobSchemaReader + { + /// + /// Read the knobs of . The context must be loaded: baseline + /// values and the rows of knobs are read from it. + /// + public static IReadOnlyList> Read( + TContext baseline, + IEnumerable>? declared = null) + where TContext : class, IDataContext + { + if (baseline is null) throw new ArgumentNullException(nameof(baseline)); + + var result = new List>(); + + // Declared knobs first: they usually rewrite a whole column (a curve), and the + // attribute knobs that follow refine single fields on top. + if (declared != null) + { + foreach (var set in declared) + { + var builder = new KnobBuilder(); + set.Declare(builder); + foreach (var knob in builder.Knobs) + { + var info = new KnobInfo + { + Id = knob.Id, + Label = knob.Label, + Group = knob.Group, + Unit = knob.Unit, + Hint = knob.Hint, + Min = knob.Min, + Max = knob.Max, + Layer = knob.Layer, + Apply = KnobApply.Set, + Baseline = knob.Read(baseline), + }; + info.Step = knob.Step > 0 ? knob.Step : NiceStep(info.Min, info.Max); + info.Editable = info.Layer == KnobLayer.Economy; + result.Add(new KnobBinding(info, result.Count, knob.Write)); + } + } + } + + foreach (var typeInfo in baseline.GetDataTypeInfos()) + { + var repositoryProperty = typeof(TContext).GetProperty( + typeInfo.PropertyName, BindingFlags.Public | BindingFlags.Instance); + if (repositoryProperty is null) continue; + + foreach (var property in typeInfo.DataType.GetProperties(BindingFlags.Public | BindingFlags.Instance)) + { + var attributes = property.GetCustomAttributes(inherit: true).ToList(); + if (attributes.Count == 0) continue; + + if (!IsNumeric(property.PropertyType) || !property.CanRead || !property.CanWrite) + { + throw new InvalidOperationException( + $"[Knob] on {typeInfo.DataType.Name}.{property.Name}: a knob needs a readable, writable " + + $"numeric property, and this one is {property.PropertyType.Name}."); + } + + foreach (var attribute in attributes) + { + foreach (var row in RowsFor(attribute, typeInfo, repositoryProperty, baseline)) + { + result.Add(BindField( + baseline, typeInfo, repositoryProperty, property, attribute, row, result.Count)); + } + } + } + } + + var duplicate = result.GroupBy(k => k.Info.Id, StringComparer.Ordinal).FirstOrDefault(g => g.Count() > 1); + if (duplicate != null) + { + throw new InvalidOperationException( + $"Two knobs share the id '{duplicate.Key}'. Give each [Knob] on one property its own Row, " + + "or pass an explicit id to the declared knob."); + } + + return result; + } + + private static IEnumerable RowsFor( + KnobAttribute attribute, DataTypeInfo typeInfo, PropertyInfo repositoryProperty, TContext baseline) + where TContext : class, IDataContext + { + if (!string.IsNullOrEmpty(attribute.Row)) + { + if (typeInfo.RepositoryKind != RepositoryKind.Table) + throw new InvalidOperationException( + $"[Knob(\"{attribute.Label}\")] on {typeInfo.DataType.Name}: Row only applies to table data."); + yield return attribute.Row; + yield break; + } + + if (attribute.EachRow && typeInfo.RepositoryKind == RepositoryKind.Table) + { + foreach (var item in Items(repositoryProperty, baseline)) + yield return KeyOf(item); + yield break; + } + + yield return null; + } + + private static KnobBinding BindField( + TContext baseline, + DataTypeInfo typeInfo, + PropertyInfo repositoryProperty, + PropertyInfo property, + KnobAttribute attribute, + string? row, + int order) + where TContext : class, IDataContext + { + var typeName = typeInfo.DataType.Name; + var integer = IsInteger(property.PropertyType); + var targets = Targets(repositoryProperty, baseline, row).ToList(); + if (targets.Count == 0) + { + throw new InvalidOperationException(row is null + ? $"[Knob(\"{attribute.Label}\")] on {typeName}.{property.Name}: the data has no rows to address." + : $"[Knob(\"{attribute.Label}\")] on {typeName}.{property.Name}: no row with Id '{row}'."); + } + + var values = targets.Select(t => ToDouble(property.GetValue(t))).ToList(); + var info = new KnobInfo + { + Id = row is null ? $"{typeName}.{property.Name}" : $"{typeName}[{row}].{property.Name}", + Label = attribute.EachRow && row != null && string.IsNullOrEmpty(attribute.Row) + ? $"{attribute.Label} · {row}" + : attribute.Label, + Group = attribute.Group, + Unit = attribute.Unit, + Hint = attribute.Hint, + Layer = attribute.Layer, + Apply = attribute.Apply, + Integer = integer && attribute.Apply != KnobApply.Scale, + Editable = attribute.Layer == KnobLayer.Economy, + Source = new KnobSource + { + DataType = typeName, + Property = property.Name, + Row = row, + File = typeInfo.FilePath, + }, + }; + + switch (attribute.Apply) + { + case KnobApply.Scale: + info.Baseline = 1; + info.Min = double.IsNaN(attribute.Min) ? 0 : attribute.Min; + info.Max = double.IsNaN(attribute.Max) ? 2 : attribute.Max; + break; + case KnobApply.Offset: + { + info.Baseline = 0; + var span = Math.Max(1, values.Max(Math.Abs)); + info.Min = double.IsNaN(attribute.Min) ? -span : attribute.Min; + info.Max = double.IsNaN(attribute.Max) ? span : attribute.Max; + break; + } + default: + { + info.Baseline = values[0]; + info.Mixed = values.Any(v => Math.Abs(v - values[0]) > 1e-9); + var top = Math.Max(1, Math.Abs(info.Baseline) * 2); + info.Min = double.IsNaN(attribute.Min) ? Math.Min(0, info.Baseline * 2) : attribute.Min; + info.Max = double.IsNaN(attribute.Max) ? top : attribute.Max; + break; + } + } + + if (!(info.Max > info.Min)) + throw new InvalidOperationException($"[Knob(\"{attribute.Label}\")] on {typeName}.{property.Name}: Max must be greater than Min."); + + info.Step = attribute.Step > 0 ? attribute.Step + : info.Integer ? Math.Max(1, Math.Round(NiceStep(info.Min, info.Max))) + : NiceStep(info.Min, info.Max); + + var apply = attribute.Apply; + void Apply(TContext data, double value) + { + foreach (var target in Targets(repositoryProperty, data, row)) + { + var current = ToDouble(property.GetValue(target)); + var next = apply switch + { + KnobApply.Scale => current * value, + KnobApply.Offset => current + value, + _ => value, + }; + property.SetValue(target, FromDouble(next, property.PropertyType)); + } + } + + return new KnobBinding(info, order, Apply); + } + + private static IEnumerable Targets(PropertyInfo repositoryProperty, TContext data, string? row) + where TContext : class, IDataContext + { + foreach (var item in Items(repositoryProperty, data)) + { + if (row is null || string.Equals(KeyOf(item), row, StringComparison.Ordinal)) + yield return item; + } + } + + /// The loaded objects of one repository on a context, in load order. + private static IEnumerable Items(PropertyInfo repositoryProperty, TContext data) + where TContext : class, IDataContext + { + var repository = repositoryProperty.GetValue(data); + switch (repository) + { + case null: + yield break; + case IEditableRepository editable: + foreach (var item in editable.EnumerateItems()) yield return item; + yield break; + } + + // Runtime (read-only) repositories expose LoadedItems / Current but not EnumerateItems. + var type = repository.GetType(); + if (type.GetProperty("LoadedItems")?.GetValue(repository) is IEnumerable loaded) + { + foreach (var pair in loaded) + { + var value = pair?.GetType().GetProperty("Value")?.GetValue(pair); + if (value != null) yield return value; + } + yield break; + } + + var current = type.GetProperty("Current")?.GetValue(repository); + if (current != null) yield return current; + } + + private static string KeyOf(object item) + { + var id = item.GetType().GetProperty("Id", BindingFlags.Public | BindingFlags.Instance)?.GetValue(item); + return Convert.ToString(id, CultureInfo.InvariantCulture) ?? string.Empty; + } + + private static bool IsInteger(Type type) + { + switch (Type.GetTypeCode(Nullable.GetUnderlyingType(type) ?? type)) + { + case TypeCode.Byte: + case TypeCode.SByte: + case TypeCode.Int16: + case TypeCode.UInt16: + case TypeCode.Int32: + case TypeCode.UInt32: + case TypeCode.Int64: + case TypeCode.UInt64: + return true; + default: + return false; + } + } + + private static bool IsNumeric(Type type) + { + if (type.IsEnum || Nullable.GetUnderlyingType(type) != null) return false; + if (IsInteger(type)) return true; + var code = Type.GetTypeCode(type); + return code == TypeCode.Single || code == TypeCode.Double || code == TypeCode.Decimal; + } + + private static double ToDouble(object? value) => value switch + { + null => 0, + // Widening a float directly drags its binary tail along (0.35f becomes + // 0.3499999940395355). Go through decimal to get the number that was written. + float f when !float.IsNaN(f) && !float.IsInfinity(f) && Math.Abs(f) < 1e28f => (double)(decimal)f, + _ => Convert.ToDouble(value, CultureInfo.InvariantCulture), + }; + + private static object FromDouble(double value, Type type) + { + if (IsInteger(type)) value = Math.Round(value, MidpointRounding.AwayFromZero); + return Convert.ChangeType(value, type, CultureInfo.InvariantCulture); + } + + /// About a hundred steps across the range, snapped to 1 / 2 / 5 × 10^n. + internal static double NiceStep(double min, double max) + { + var raw = (max - min) / 100.0; + if (!(raw > 0)) return 1; + var magnitude = Math.Pow(10, Math.Floor(Math.Log10(raw))); + foreach (var m in new[] { 1.0, 2.0, 5.0, 10.0 }) + { + if (m * magnitude >= raw - 1e-12) return m * magnitude; + } + return raw; + } + } +} diff --git a/Datra.Lab/LabEngine.cs b/Datra.Lab/LabEngine.cs new file mode 100644 index 0000000..c5fea6e --- /dev/null +++ b/Datra.Lab/LabEngine.cs @@ -0,0 +1,291 @@ +#nullable enable +using System; +using System.Collections.Generic; +using System.Diagnostics; +using System.Linq; +using System.Threading; +using System.Threading.Tasks; +using Datra.Attributes; +using Datra.Interfaces; + +namespace Datra.Lab +{ + /// + /// The lab without its generic parameter, for hosts (endpoints, a console tool) that only + /// pass schemas, scenarios and results around. + /// + public interface ILabEngine + { + /// The knobs and settings of this lab, with baseline values. + Task GetSchemaAsync(CancellationToken cancellationToken = default); + + /// Lay the scenario over the baseline, play the bots and aggregate. + /// The scenario names an unknown knob or policy, or an invalid value. + Task RunAsync(Scenario scenario, CancellationToken cancellationToken = default); + + /// Run the scenario and store it, with its result, under . + Task SaveSnapshotAsync(string name, Scenario scenario, CancellationToken cancellationToken = default); + + /// The snapshot store, or null when snapshots are off. + ISnapshotStore? Snapshots { get; } + + /// Forget the cached baseline. Call after the saved data changed. + void InvalidateBaseline(); + } + + /// A scenario the lab cannot run as written. The message is meant for the person who sent it. + public sealed class ScenarioException : Exception + { + public ScenarioException(string message) : base(message) { } + } + + /// + /// Ties the pieces together for one data context and one simulator: forks the baseline, + /// applies a scenario's knobs to the fork, plays the bots and aggregates their records. + /// + public sealed class LabEngine : ILabEngine where TContext : class, IDataContext + { + private readonly ContextForker _forker; + private readonly ISimulator _simulator; + private readonly LabOptions _options; + private readonly SemaphoreSlim _gate = new SemaphoreSlim(1, 1); + private Baseline? _baseline; + + /// Where the baseline data is read from. The lab never writes to it. + public LabEngine(IRawDataProvider source, ISimulator simulator, LabOptions? options = null) + { + _simulator = simulator ?? throw new ArgumentNullException(nameof(simulator)); + _options = options ?? new LabOptions(); + _forker = new ContextForker(source, _options.CreateContext); + } + + public ISnapshotStore? Snapshots => _options.Snapshots; + + public void InvalidateBaseline() + { + _forker.Invalidate(); + Volatile.Write(ref _baseline, null); + } + + public async Task GetSchemaAsync(CancellationToken cancellationToken = default) + { + var baseline = await EnsureBaselineAsync(cancellationToken).ConfigureAwait(false); + var schema = new LabSchema + { + Title = _options.Title, + Context = typeof(TContext).Name, + BaselineHash = baseline.Hash, + Knobs = baseline.Knobs.Select(k => k.Info).ToList(), + Policies = Policies().ToList(), + PolicyParams = _options.PolicyParams.ToList(), + Checks = _options.Checks.Select(c => new CheckInfo { Name = c.Name, Unit = c.Unit, Target = c.Target }).ToList(), + Snapshots = _options.Snapshots != null, + OutcomeVersion = _options.Outcomes?.Version, + }; + schema.Defaults = new LabDefaults { Bots = _options.Bots, MaxBots = _options.MaxBots, Seed = _options.Seed, Policy = schema.Policies[0].Id }; + return schema; + } + + /// + /// A loaded context with the scenario's knobs applied: what a simulator is handed. The + /// caller owns it; nothing done to it reaches the baseline or the saved data. + /// + public async Task ForkAsync(Scenario? scenario = null, CancellationToken cancellationToken = default) + { + var baseline = await EnsureBaselineAsync(cancellationToken).ConfigureAwait(false); + var changes = Resolve(baseline, scenario ?? new Scenario()); + return await ForkAsync(changes).ConfigureAwait(false); + } + + public async Task RunAsync(Scenario scenario, CancellationToken cancellationToken = default) + { + if (scenario is null) throw new ArgumentNullException(nameof(scenario)); + + var baseline = await EnsureBaselineAsync(cancellationToken).ConfigureAwait(false); + var changes = Resolve(baseline, scenario); + var settings = Settings(scenario); + + var watch = Stopwatch.StartNew(); + var data = await ForkAsync(changes).ConfigureAwait(false); + + // The bots are CPU work; keep them off the caller's thread (a request thread, a UI thread). + var records = await Task.Run( + () => BotRunner.Run(_simulator, data, settings, _options.Outcomes, cancellationToken), + cancellationToken).ConfigureAwait(false); + + var result = ResultAggregator.Aggregate(records, _options.Checks); + watch.Stop(); + + result.BaselineHash = baseline.Hash; + result.OutcomeVersion = _options.Outcomes?.Version; + result.Scenario = new Scenario + { + Name = scenario.Name ?? string.Empty, + Changes = changes.ToDictionary(c => c.Knob.Info.Id, c => c.Value, StringComparer.Ordinal), + Bots = settings.Bots, + Seed = settings.Seed, + Policy = settings.Policy, + PolicyParams = new Dictionary(settings.PolicyParams, StringComparer.Ordinal), + }; + result.Timing = new RunTiming + { + ElapsedMs = watch.Elapsed.TotalMilliseconds, + SimulatedSeconds = records.Sum(r => r.TotalSeconds), + }; + return result; + } + + public async Task SaveSnapshotAsync(string name, Scenario scenario, CancellationToken cancellationToken = default) + { + var store = _options.Snapshots + ?? throw new InvalidOperationException("Snapshots are off: no snapshot store was configured."); + if (!FileSnapshotStore.IsValidName(name)) + throw new ScenarioException("A snapshot name is 1-80 letters, digits, spaces or . _ + - and starts with a letter or digit."); + + var result = await RunAsync(scenario, cancellationToken).ConfigureAwait(false); + result.Scenario.Name = name; + var snapshot = new LabSnapshot + { + Name = name, + CreatedAtUtc = DateTimeOffset.UtcNow, + BaselineHash = result.BaselineHash, + Scenario = result.Scenario, + Result = result, + }; + await store.SaveAsync(snapshot).ConfigureAwait(false); + return snapshot; + } + + private async Task ForkAsync(List changes) + { + var data = await _forker.ForkAsync().ConfigureAwait(false); + + // Knobs declared in code first (they rewrite whole columns), then attribute knobs + // in the order Set, Scale, Offset so several knobs on one field compose the same + // way whatever order the scenario lists them in. + foreach (var change in changes.OrderBy(c => Pass(c.Knob.Info)).ThenBy(c => c.Knob.Order)) + change.Knob.Apply(data, change.Value); + return data; + } + + private static int Pass(KnobInfo info) + { + if (info.Source is null) return 0; + return info.Apply switch { KnobApply.Set => 1, KnobApply.Scale => 2, _ => 3 }; + } + + private List Resolve(Baseline baseline, Scenario scenario) + { + var changes = new List(); + if (scenario.Changes is null) return changes; + + foreach (var pair in scenario.Changes) + { + var knob = baseline.Knobs.FirstOrDefault(k => string.Equals(k.Info.Id, pair.Key, StringComparison.Ordinal)) + ?? throw new ScenarioException($"Unknown knob '{pair.Key}'."); + if (double.IsNaN(pair.Value) || double.IsInfinity(pair.Value)) + throw new ScenarioException($"Knob '{pair.Key}' needs a finite value."); + + // A knob sitting on its baseline is not a change; drop it so results compare equal. + if (Math.Abs(pair.Value - knob.Info.Baseline) < 1e-12) continue; + + if (!knob.Info.Editable) + { + throw new ScenarioException( + $"Knob '{pair.Key}' reaches the physics layer. Physics knobs are read-only until stored outcomes can be recomputed."); + } + changes.Add(new Change(knob, pair.Value)); + } + return changes; + } + + private RunSettings Settings(Scenario scenario) + { + var policies = Policies().ToList(); + var policy = scenario.Policy ?? policies[0].Id; + if (!policies.Any(p => string.Equals(p.Id, policy, StringComparison.Ordinal))) + throw new ScenarioException($"Unknown policy '{policy}'."); + + var bots = scenario.Bots ?? _options.Bots; + if (bots < 1 || bots > _options.MaxBots) + throw new ScenarioException($"Bots must be between 1 and {_options.MaxBots}."); + + var settings = new RunSettings + { + Bots = bots, + Seed = scenario.Seed ?? _options.Seed, + Policy = policy, + MaxSimSeconds = _options.MaxSimSeconds, + MaxParallelism = _options.MaxParallelism, + }; + + foreach (var param in _options.PolicyParams) + settings.PolicyParams[param.Id] = param.Default; + if (scenario.PolicyParams != null) + { + foreach (var pair in scenario.PolicyParams) + { + if (!settings.PolicyParams.ContainsKey(pair.Key)) + throw new ScenarioException($"Unknown policy parameter '{pair.Key}'."); + if (double.IsNaN(pair.Value) || double.IsInfinity(pair.Value)) + throw new ScenarioException($"Policy parameter '{pair.Key}' needs a finite value."); + settings.PolicyParams[pair.Key] = pair.Value; + } + } + return settings; + } + + private IEnumerable Policies() => + _options.Policies.Count > 0 + ? _options.Policies + : new List { new PolicyInfo { Id = "default", Label = "Default" } }; + + private async Task EnsureBaselineAsync(CancellationToken cancellationToken) + { + var baseline = Volatile.Read(ref _baseline); + if (baseline != null) return baseline; + + await _gate.WaitAsync(cancellationToken).ConfigureAwait(false); + try + { + baseline = Volatile.Read(ref _baseline); + if (baseline != null) return baseline; + + var data = await _forker.ForkAsync().ConfigureAwait(false); + baseline = new Baseline( + KnobSchemaReader.Read(data, _options.KnobSets), + _forker.Snapshot.ComputeHash()); + Volatile.Write(ref _baseline, baseline); + return baseline; + } + finally + { + _gate.Release(); + } + } + + private sealed class Baseline + { + public Baseline(IReadOnlyList> knobs, string hash) + { + Knobs = knobs; + Hash = hash; + } + + public IReadOnlyList> Knobs { get; } + public string Hash { get; } + } + + private readonly struct Change + { + public Change(KnobBinding knob, double value) + { + Knob = knob; + Value = value; + } + + public KnobBinding Knob { get; } + public double Value { get; } + } + } +} diff --git a/Datra.Lab/LabJson.cs b/Datra.Lab/LabJson.cs new file mode 100644 index 0000000..5120ddf --- /dev/null +++ b/Datra.Lab/LabJson.cs @@ -0,0 +1,40 @@ +#nullable enable +using System.Text.Encodings.Web; +using System.Text.Json; +using System.Text.Json.Serialization; + +namespace Datra.Lab +{ + /// + /// The one JSON shape the lab speaks: camelCase properties, camelCase enum names, nulls + /// left out. Endpoints, snapshot files and (later) exported pages all use it, so the view + /// modules read the same document wherever it came from. + /// + public static class LabJson + { + public static JsonSerializerOptions Options { get; } = Create(indented: false); + + private static readonly JsonSerializerOptions Indented = Create(indented: true); + + public static string Serialize(T value, bool indented = false) => + JsonSerializer.Serialize(value, indented ? Indented : Options); + + public static T? Deserialize(string json) where T : class => + JsonSerializer.Deserialize(json, Options); + + private static JsonSerializerOptions Create(bool indented) + { + var options = new JsonSerializerOptions + { + PropertyNamingPolicy = JsonNamingPolicy.CamelCase, + PropertyNameCaseInsensitive = true, + DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull, + WriteIndented = indented, + // Snapshot files are read by people: keep non-ASCII labels as they were typed. + Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping, + }; + options.Converters.Add(new JsonStringEnumConverter(JsonNamingPolicy.CamelCase)); + return options; + } + } +} diff --git a/Datra.Lab/LabOptions.cs b/Datra.Lab/LabOptions.cs new file mode 100644 index 0000000..57a50dc --- /dev/null +++ b/Datra.Lab/LabOptions.cs @@ -0,0 +1,115 @@ +#nullable enable +using System; +using System.Collections.Generic; +using Datra.Interfaces; + +namespace Datra.Lab +{ + /// + /// What a game tells the lab beyond its attributes and its simulator: bot defaults, + /// policies, knobs declared in code, checks, stored physics outcomes and where snapshots go. + /// + public sealed class LabOptions where TContext : class, IDataContext + { + internal List> KnobSets { get; } = new List>(); + internal List Checks { get; } = new List(); + internal List Policies { get; } = new List(); + internal List PolicyParams { get; } = new List(); + + /// Shown at the top of the lab screen. + public string Title { get; set; } = "Balance lab"; + + /// Default number of bots per run. + public int Bots { get; set; } = 40; + + /// Default base seed. + public int Seed { get; set; } = 1; + + /// Most bots one request may ask for. + public int MaxBots { get; set; } = 400; + + /// Game-time cap per bot, in seconds. + public double MaxSimSeconds { get; set; } = 12 * 3600; + + /// Threads per run. Zero means one per processor. + public int MaxParallelism { get; set; } + + /// Stored physics outcomes the simulator draws from through . + public IOutcomeReader? Outcomes { get; set; } + + /// Where snapshots are kept. Null turns snapshots off. + public ISnapshotStore? Snapshots { get; set; } + + /// + /// Builds a context on a given provider. Leave null to use the generated + /// (IRawDataProvider, ...optional) constructor. + /// + public Func? CreateContext { get; set; } + + /// Keep snapshots as JSON files in . + public LabOptions SnapshotDirectory(string directory) + { + Snapshots = new FileSnapshotStore(directory); + return this; + } + + /// Offer a bot policy. The first one added is the default. + public LabOptions Policy(string id, string? label = null, string hint = "") + { + if (string.IsNullOrWhiteSpace(id)) throw new ArgumentException("A policy needs an id.", nameof(id)); + Policies.Add(new PolicyInfo { Id = id, Label = label ?? id, Hint = hint }); + return this; + } + + /// + /// Declare a number the policies are tuned by. The simulator reads it with + /// . + /// + public LabOptions PolicyParam( + string id, string label, double @default, double min, double max, double step = 0, string unit = "") + { + if (string.IsNullOrWhiteSpace(id)) throw new ArgumentException("A policy parameter needs an id.", nameof(id)); + if (!(max > min)) throw new ArgumentException($"Policy parameter '{id}': max must be greater than min."); + PolicyParams.Add(new PolicyParamInfo + { + Id = id, + Label = label, + Unit = unit, + Default = @default, + Min = min, + Max = max, + Step = step > 0 ? step : KnobSchemaReader.NiceStep(min, max), + }); + return this; + } + + /// Add knobs that an attribute cannot express. + public LabOptions Knobs(IKnobSet set) + { + KnobSets.Add(set ?? throw new ArgumentNullException(nameof(set))); + return this; + } + + /// + public LabOptions Knobs(Action> declare) + { + if (declare is null) throw new ArgumentNullException(nameof(declare)); + KnobSets.Add(new DelegateKnobSet(declare)); + return this; + } + + /// Add a number to watch against a target. See . + public LabOptions Check(string name, Func metric, string target, string unit = "") + { + Checks.Add(new LabCheck(name, metric, target, unit)); + return this; + } + + private sealed class DelegateKnobSet : IKnobSet + { + private readonly Action> _declare; + public DelegateKnobSet(Action> declare) => _declare = declare; + public void Declare(KnobBuilder knobs) => _declare(knobs); + } + } +} diff --git a/Datra.Lab/LabSchema.cs b/Datra.Lab/LabSchema.cs new file mode 100644 index 0000000..5559cfa --- /dev/null +++ b/Datra.Lab/LabSchema.cs @@ -0,0 +1,69 @@ +#nullable enable +using System.Collections.Generic; + +namespace Datra.Lab +{ + /// + /// Everything a front end needs to build the lab screen for one game without knowing the + /// game: the knobs, the bot settings on offer, the checks and the defaults. + /// + public sealed class LabSchema + { + public string Title { get; set; } = string.Empty; + + /// CLR name of the data context the knobs were read from. + public string Context { get; set; } = string.Empty; + + /// Hash of the baseline data. Changes when the saved data does. + public string BaselineHash { get; set; } = string.Empty; + + public List Knobs { get; set; } = new List(); + public List Policies { get; set; } = new List(); + public List PolicyParams { get; set; } = new List(); + public List Checks { get; set; } = new List(); + public LabDefaults Defaults { get; set; } = new LabDefaults(); + + /// Snapshots can be saved and loaded. + public bool Snapshots { get; set; } + + /// Version of the stored physics outcomes, when the lab has any. + public string? OutcomeVersion { get; set; } + } + + public sealed class PolicyInfo + { + public string Id { get; set; } = string.Empty; + public string Label { get; set; } = string.Empty; + public string Hint { get; set; } = string.Empty; + } + + /// A number a bot policy is tuned by. A scenario setting, not a knob: it is not game data. + public sealed class PolicyParamInfo + { + public string Id { get; set; } = string.Empty; + public string Label { get; set; } = string.Empty; + public string Unit { get; set; } = string.Empty; + public double Default { get; set; } + public double Min { get; set; } + public double Max { get; set; } + public double Step { get; set; } + } + + public sealed class CheckInfo + { + public string Name { get; set; } = string.Empty; + public string Unit { get; set; } = string.Empty; + public string Target { get; set; } = string.Empty; + } + + public sealed class LabDefaults + { + public int Bots { get; set; } + + /// Most bots one run may ask for. + public int MaxBots { get; set; } + + public int Seed { get; set; } + public string Policy { get; set; } = string.Empty; + } +} diff --git a/Datra.Lab/Outcomes/IOutcomeReader.cs b/Datra.Lab/Outcomes/IOutcomeReader.cs new file mode 100644 index 0000000..fc5917e --- /dev/null +++ b/Datra.Lab/Outcomes/IOutcomeReader.cs @@ -0,0 +1,111 @@ +#nullable enable +using System; +using System.Collections.Concurrent; +using System.Collections.Generic; +using System.IO; +using System.Linq; +using System.Text.Json; + +namespace Datra.Lab +{ + /// + /// Read side of the physics cache: for a , the pool of outcomes a + /// physics batch produced earlier. The economy layer draws from the pool instead of running + /// physics. Implementations are read from several threads at once. + /// + /// + /// P0 only reads. Noticing a missing key, queueing a batch and filling the cache are not + /// part of this contract yet. + /// + public interface IOutcomeReader + { + /// Engine pin + recipe hash: what the stored outcomes were computed with. + string Version { get; } + + /// The stored outcomes for , or null when none are cached. + IReadOnlyList? Pool(PhysicsKey key); + } + + /// Thrown by when the cache has nothing for a key. + public sealed class MissingOutcomeException : Exception + { + public MissingOutcomeException(PhysicsKey key) + : base($"No stored physics outcomes for '{key.Text}'.") + { + Key = key; + } + + public PhysicsKey Key { get; } + } + + /// Outcome pools held in memory. For tests, samples and small hand-made tables. + public sealed class InMemoryOutcomes : IOutcomeReader + { + private readonly ConcurrentDictionary _pools = + new ConcurrentDictionary(StringComparer.Ordinal); + + public InMemoryOutcomes(string version = "memory") + { + Version = version; + } + + public string Version { get; } + + public int Count => _pools.Count; + + public InMemoryOutcomes Add(PhysicsKey key, IEnumerable samples) + { + _pools[key.Text] = samples.ToList(); + return this; + } + + public IReadOnlyList? Pool(PhysicsKey key) => + _pools.TryGetValue(key.Text, out var pool) ? pool as IReadOnlyList : null; + } + + /// + /// Reads outcome pools from a directory of JSON Lines files: one file per key, named + /// {PhysicsKey.Hash(version)}.jsonl, one outcome per line. Files are parsed on first + /// use and kept. + /// + public sealed class JsonlOutcomeReader : IOutcomeReader + { + private readonly string _directory; + private readonly JsonSerializerOptions _json; + private readonly ConcurrentDictionary _pools = + new ConcurrentDictionary(StringComparer.Ordinal); + + public JsonlOutcomeReader(string directory, string version, JsonSerializerOptions? json = null) + { + _directory = directory ?? throw new ArgumentNullException(nameof(directory)); + Version = version ?? string.Empty; + _json = json ?? new JsonSerializerOptions { PropertyNameCaseInsensitive = true }; + } + + public string Version { get; } + + /// The file a key's outcomes are read from. + public string PathFor(PhysicsKey key) => Path.Combine(_directory, key.Hash(Version) + ".jsonl"); + + public IReadOnlyList? Pool(PhysicsKey key) + { + var cacheKey = typeof(T).FullName + "|" + key.Text; + return _pools.GetOrAdd(cacheKey, _ => Load(key)) as IReadOnlyList; + } + + private object? Load(PhysicsKey key) + { + var path = PathFor(key); + if (!File.Exists(path)) return null; + + var pool = new List(); + foreach (var line in File.ReadLines(path)) + { + if (string.IsNullOrWhiteSpace(line)) continue; + var sample = JsonSerializer.Deserialize(line, _json); + if (sample != null) pool.Add(sample); + } + return pool.Count == 0 ? null : pool; + } + } +} diff --git a/Datra.Lab/Outcomes/PhysicsKey.cs b/Datra.Lab/Outcomes/PhysicsKey.cs new file mode 100644 index 0000000..f7ef8cb --- /dev/null +++ b/Datra.Lab/Outcomes/PhysicsKey.cs @@ -0,0 +1,68 @@ +#nullable enable +using System; +using System.Globalization; +using System.Linq; +using System.Security.Cryptography; +using System.Text; + +namespace Datra.Lab +{ + /// + /// Identifies one physics state: the inputs that decide how a run plays out, as sorted + /// name=value pairs. Datra treats it as an opaque string; what goes in is the game's. + /// + public sealed class PhysicsKey : IEquatable + { + private PhysicsKey(string text) + { + Text = text; + } + + /// Canonical form, e.g. floor=B3;push=2. + public string Text { get; } + + /// + /// Build a key from named inputs. Order does not matter; numbers are written + /// culture-invariantly so the same inputs always give the same key. + /// + public static PhysicsKey Of(params (string Name, object? Value)[] parts) + { + if (parts is null) throw new ArgumentNullException(nameof(parts)); + var pairs = parts + .OrderBy(p => p.Name, StringComparer.Ordinal) + .Select(p => p.Name + "=" + Format(p.Value)); + return new PhysicsKey(string.Join(";", pairs)); + } + + /// A key from text already in canonical form (read back from a cache index). + public static PhysicsKey Parse(string text) => new PhysicsKey(text ?? throw new ArgumentNullException(nameof(text))); + + /// + /// Short hex digest of the key together with the outcome source version. Used as a + /// file name by . + /// + public string Hash(string version = "") + { + using var sha = SHA256.Create(); + var bytes = sha.ComputeHash(Encoding.UTF8.GetBytes(version + "|" + Text)); + var hex = new StringBuilder(16); + for (var i = 0; i < 8; i++) hex.Append(bytes[i].ToString("x2")); + return hex.ToString(); + } + + private static string Format(object? value) => value switch + { + null => string.Empty, + bool b => b ? "true" : "false", + float f => f.ToString("R", CultureInfo.InvariantCulture), + double d => d.ToString("R", CultureInfo.InvariantCulture), + IFormattable formattable => formattable.ToString(null, CultureInfo.InvariantCulture), + _ => value.ToString() ?? string.Empty, + }; + + public bool Equals(PhysicsKey? other) => other != null && string.Equals(Text, other.Text, StringComparison.Ordinal); + public override bool Equals(object? obj) => Equals(obj as PhysicsKey); + public override int GetHashCode() => StringComparer.Ordinal.GetHashCode(Text); + public override string ToString() => Text; + } +} diff --git a/Datra.Lab/Results/LabCheck.cs b/Datra.Lab/Results/LabCheck.cs new file mode 100644 index 0000000..b611ef6 --- /dev/null +++ b/Datra.Lab/Results/LabCheck.cs @@ -0,0 +1,51 @@ +#nullable enable +using System; +using System.Globalization; +using System.Text.RegularExpressions; + +namespace Datra.Lab +{ + /// + /// A number the game cares about, with the value it should have: "first purchase within a + /// minute", "no run longer than 90 seconds". Measured per bot; the median is reported. + /// + public sealed class LabCheck + { + private static readonly Regex TargetPattern = new Regex( + @"^\s*(<=|>=|<|>|=)\s*(-?\d+(?:\.\d+)?)\s*$", RegexOptions.CultureInvariant); + + private readonly string _operator; + private readonly double _bound; + + /// The value for one bot. Return NaN when the bot has none (it never bought anything). + /// A comparison against a number: "<= 60", "> 3", "= 5". + public LabCheck(string name, Func metric, string target, string unit = "") + { + if (string.IsNullOrWhiteSpace(name)) throw new ArgumentException("A check needs a name.", nameof(name)); + Name = name; + Metric = metric ?? throw new ArgumentNullException(nameof(metric)); + Unit = unit ?? string.Empty; + + var match = TargetPattern.Match(target ?? string.Empty); + if (!match.Success) + throw new ArgumentException($"Check '{name}': target '{target}' is not of the form \"<= 60\".", nameof(target)); + _operator = match.Groups[1].Value; + _bound = double.Parse(match.Groups[2].Value, CultureInfo.InvariantCulture); + Target = _operator + " " + match.Groups[2].Value; + } + + public string Name { get; } + public string Unit { get; } + public string Target { get; } + public Func Metric { get; } + + public bool IsMet(double value) => _operator switch + { + "<=" => value <= _bound, + ">=" => value >= _bound, + "<" => value < _bound, + ">" => value > _bound, + _ => Math.Abs(value - _bound) < 1e-9, + }; + } +} diff --git a/Datra.Lab/Results/LabResult.cs b/Datra.Lab/Results/LabResult.cs new file mode 100644 index 0000000..0f99db3 --- /dev/null +++ b/Datra.Lab/Results/LabResult.cs @@ -0,0 +1,184 @@ +#nullable enable +using System.Collections.Generic; + +namespace Datra.Lab +{ + /// + /// What a batch of bots amounted to, in the shape the views draw from. All times are + /// seconds of game time. + /// + public sealed class LabResult + { + /// The scenario as it was run, with defaults filled in. + public Scenario Scenario { get; set; } = new Scenario(); + + /// Hash of the baseline data the scenario was laid over. + public string BaselineHash { get; set; } = string.Empty; + + /// Version of the stored physics outcomes the bots drew from, if any. + public string? OutcomeVersion { get; set; } + + public int Bots { get; set; } + + /// Bots that played to the end. + public int Finished { get; set; } + + /// Time to play through, over the bots that finished. Null when none did. + public Quantiles? Total { get; set; } + + public List Stages { get; set; } = new List(); + public ProgressionResult Progression { get; set; } = new ProgressionResult(); + public PurchaseTimeline Purchases { get; set; } = new PurchaseTimeline(); + public TickSummary Ticks { get; set; } = new TickSummary(); + public List Checks { get; set; } = new List(); + public List Marks { get; set; } = new List(); + public List Explains { get; set; } = new List(); + + /// Things that make the numbers less trustworthy: unfinished bots, errors, missing physics. + public List Problems { get; set; } = new List(); + + /// How long the computation took. The only part that differs between two identical runs. + public RunTiming? Timing { get; set; } + } + + /// Median and the 10th / 90th percentile across bots. + public sealed class Quantiles + { + public double Median { get; set; } + public double P10 { get; set; } + public double P90 { get; set; } + } + + public sealed class StageResult + { + public string Id { get; set; } = string.Empty; + public string Label { get; set; } = string.Empty; + public double? TargetSeconds { get; set; } + + /// Bots that entered the stage. + public int Reached { get; set; } + + /// Bots that left it again. The quantiles are over these. + public int Completed { get; set; } + + public double? Median { get; set; } + public double? P10 { get; set; } + public double? P90 { get; set; } + } + + /// + /// Where the bots are over time. Depth is the stage index plus the fraction of the stage + /// done, so 2.5 is halfway through the third stage and stages.Count is the end. + /// + public sealed class ProgressionResult + { + public double TMax { get; set; } + public List Points { get; set; } = new List(); + } + + public sealed class ProgressionPoint + { + public double T { get; set; } + public double P10 { get; set; } + public double Median { get; set; } + public double P90 { get; set; } + } + + /// The purchases of one representative bot: the one whose total time is closest to the median. + public sealed class PurchaseTimeline + { + public int Bot { get; set; } + public int Seed { get; set; } + + /// Median time of the first purchase across all bots. Null when no bot bought anything. + public double? FirstSeconds { get; set; } + + /// Median number of purchases per bot. + public double CountMedian { get; set; } + + /// Lanes, in order of first appearance. + public List Groups { get; set; } = new List(); + + /// When the representative bot left each stage. + public List StageEnds { get; set; } = new List(); + + public List Items { get; set; } = new List(); + } + + public sealed class StageEnd + { + public string Id { get; set; } = string.Empty; + public double T { get; set; } + } + + public sealed class PurchaseItem + { + public double T { get; set; } + public string Id { get; set; } = string.Empty; + public string Label { get; set; } = string.Empty; + public double Cost { get; set; } + public string Group { get; set; } = string.Empty; + public string Stage { get; set; } = string.Empty; + } + + public sealed class TickSummary + { + /// Median number of ticks per bot. + public double CountMedian { get; set; } + + /// Longest single tick of each kind, across all bots. + public Dictionary LongestSeconds { get; set; } = new Dictionary(); + + /// Median total earned per bot. + public double EarnedMedian { get; set; } + } + + public sealed class CheckResult + { + public string Name { get; set; } = string.Empty; + public string Unit { get; set; } = string.Empty; + public string Target { get; set; } = string.Empty; + + /// Median of the metric across bots. Null when no bot produced a value. + public double? Value { get; set; } + + /// Whether the value meets the target. Null when there is no value. + public bool? Ok { get; set; } + } + + public sealed class MarkResult + { + public string Name { get; set; } = string.Empty; + + /// Bots that wrote the mark at least once. + public int Bots { get; set; } + + /// Median time of the first occurrence, over those bots. + public double FirstSeconds { get; set; } + } + + public sealed class ExplainResult + { + public string Stage { get; set; } = string.Empty; + public string Text { get; set; } = string.Empty; + + /// Bots that gave this reason. + public int Bots { get; set; } + } + + public sealed class ResultProblem + { + /// unfinished, error or missingOutcome. + public string Kind { get; set; } = string.Empty; + public string Message { get; set; } = string.Empty; + public int Bots { get; set; } + } + + public sealed class RunTiming + { + public double ElapsedMs { get; set; } + + /// Game time played by all bots together. + public double SimulatedSeconds { get; set; } + } +} diff --git a/Datra.Lab/Results/ResultAggregator.cs b/Datra.Lab/Results/ResultAggregator.cs new file mode 100644 index 0000000..0e2a46c --- /dev/null +++ b/Datra.Lab/Results/ResultAggregator.cs @@ -0,0 +1,343 @@ +#nullable enable +using System; +using System.Collections.Generic; +using System.Linq; + +namespace Datra.Lab +{ + /// + /// Turns the bots' records into one . Pure: the same records in the + /// same order give the same result. + /// + public static class ResultAggregator + { + /// Number of points on the progression curve. + public const int ProgressionSamples = 120; + + public static LabResult Aggregate(IReadOnlyList records, IEnumerable? checks = null) + { + if (records is null) throw new ArgumentNullException(nameof(records)); + + var result = new LabResult { Bots = records.Count }; + var finished = records.Where(r => r.Finished).ToList(); + result.Finished = finished.Count; + + if (finished.Count > 0) + result.Total = Of(finished.Select(r => r.TotalSeconds)); + + var stageOrder = StageOrder(records); + result.Stages = Stages(records, stageOrder); + result.Progression = Progression(records, stageOrder); + + var representative = Representative(records, finished, result.Total); + result.Purchases = Purchases(records, representative); + result.Ticks = Ticks(records); + result.Marks = Marks(records); + result.Explains = Explains(records, stageOrder); + result.Problems = Problems(records); + + if (checks != null) + { + foreach (var check in checks) + { + var values = records.Select(check.Metric).Where(v => !double.IsNaN(v) && !double.IsInfinity(v)).ToList(); + var entry = new CheckResult { Name = check.Name, Unit = check.Unit, Target = check.Target }; + if (values.Count > 0) + { + entry.Value = Percentile(Sorted(values), 0.5); + entry.Ok = check.IsMet(entry.Value.Value); + } + result.Checks.Add(entry); + } + } + + return result; + } + + /// Linear-interpolated percentile of an ascending list. + public static double Percentile(IReadOnlyList sorted, double q) + { + if (sorted.Count == 0) return double.NaN; + if (sorted.Count == 1) return sorted[0]; + var position = q * (sorted.Count - 1); + var lower = (int)Math.Floor(position); + var upper = Math.Min(sorted.Count - 1, lower + 1); + return sorted[lower] + (sorted[upper] - sorted[lower]) * (position - lower); + } + + private static List Sorted(IEnumerable values) + { + var list = values.ToList(); + list.Sort(); + return list; + } + + private static Quantiles Of(IEnumerable values) + { + var sorted = Sorted(values); + return new Quantiles + { + Median = Percentile(sorted, 0.5), + P10 = Percentile(sorted, 0.1), + P90 = Percentile(sorted, 0.9), + }; + } + + /// Stage ids in the order bots first meet them. + private static List StageOrder(IReadOnlyList records) + { + var order = new List(); + var seen = new HashSet(StringComparer.Ordinal); + foreach (var record in records) + { + foreach (var stage in record.Stages) + { + if (seen.Add(stage.Id)) order.Add(stage); + } + } + return order; + } + + private static List Stages(IReadOnlyList records, List order) + { + var list = new List(order.Count); + foreach (var first in order) + { + var durations = new List(); + var reached = 0; + foreach (var record in records) + { + var visits = record.Stages.Where(s => s.Id == first.Id).ToList(); + if (visits.Count == 0) continue; + reached++; + // A stage the bot was still in when it stopped has no length yet. + if (visits.All(v => v.EndSeconds.HasValue)) + durations.Add(visits.Sum(v => v.EndSeconds!.Value - v.StartSeconds)); + } + + var entry = new StageResult + { + Id = first.Id, + Label = first.Label, + TargetSeconds = first.TargetSeconds, + Reached = reached, + Completed = durations.Count, + }; + if (durations.Count > 0) + { + var q = Of(durations); + entry.Median = q.Median; + entry.P10 = q.P10; + entry.P90 = q.P90; + } + list.Add(entry); + } + return list; + } + + private static ProgressionResult Progression(IReadOnlyList records, List order) + { + var progression = new ProgressionResult(); + if (records.Count == 0 || order.Count == 0) return progression; + + var index = new Dictionary(StringComparer.Ordinal); + for (var i = 0; i < order.Count; i++) index[order[i].Id] = i; + + var tMax = records.Max(r => r.TotalSeconds); + progression.TMax = tMax; + if (!(tMax > 0)) return progression; + + var depths = new double[records.Count]; + var cursors = new int[records.Count]; + for (var sample = 0; sample <= ProgressionSamples; sample++) + { + var t = tMax * sample / ProgressionSamples; + for (var b = 0; b < records.Count; b++) + { + var record = records[b]; + if (record.Finished && t >= record.TotalSeconds) + { + depths[b] = order.Count; + continue; + } + + // Progress points are in time order and t only grows, so walk a cursor. + var points = record.Progress; + var cursor = cursors[b]; + while (cursor + 1 < points.Count && points[cursor + 1].Time <= t) cursor++; + cursors[b] = cursor; + + if (points.Count == 0 || points[cursor].Time > t) + { + depths[b] = 0; + continue; + } + + var point = points[cursor]; + depths[b] = index[record.Stages[point.Stage].Id] + point.Fraction; + } + + var sorted = Sorted(depths); + progression.Points.Add(new ProgressionPoint + { + T = t, + P10 = Percentile(sorted, 0.1), + Median = Percentile(sorted, 0.5), + P90 = Percentile(sorted, 0.9), + }); + } + return progression; + } + + /// The finished bot whose total is closest to the median; the first bot when none finished. + private static BotRecord? Representative(IReadOnlyList records, List finished, Quantiles? total) + { + if (records.Count == 0) return null; + if (finished.Count == 0 || total is null) return records[0]; + + var best = finished[0]; + foreach (var record in finished) + { + if (Math.Abs(record.TotalSeconds - total.Median) < Math.Abs(best.TotalSeconds - total.Median)) + best = record; + } + return best; + } + + private static PurchaseTimeline Purchases(IReadOnlyList records, BotRecord? representative) + { + var timeline = new PurchaseTimeline(); + if (records.Count == 0) return timeline; + + var firsts = records.Where(r => r.Purchases.Count > 0).Select(r => r.FirstPurchaseSeconds).ToList(); + if (firsts.Count > 0) timeline.FirstSeconds = Percentile(Sorted(firsts), 0.5); + timeline.CountMedian = Percentile(Sorted(records.Select(r => (double)r.Purchases.Count)), 0.5); + + if (representative is null) return timeline; + timeline.Bot = representative.Bot; + timeline.Seed = representative.Seed; + + foreach (var stage in representative.Stages) + { + if (stage.EndSeconds.HasValue) + timeline.StageEnds.Add(new StageEnd { Id = stage.Id, T = stage.EndSeconds.Value }); + } + + foreach (var purchase in representative.Purchases) + { + if (!timeline.Groups.Contains(purchase.Group)) timeline.Groups.Add(purchase.Group); + timeline.Items.Add(new PurchaseItem + { + T = purchase.Time, + Id = purchase.Id, + Label = purchase.Label, + Cost = purchase.Cost, + Group = purchase.Group, + Stage = purchase.Stage >= 0 ? representative.Stages[purchase.Stage].Id : string.Empty, + }); + } + return timeline; + } + + private static TickSummary Ticks(IReadOnlyList records) + { + var summary = new TickSummary(); + if (records.Count == 0) return summary; + + summary.CountMedian = Percentile(Sorted(records.Select(r => (double)r.Ticks.Count)), 0.5); + summary.EarnedMedian = Percentile(Sorted(records.Select(r => r.TotalEarned)), 0.5); + + var longest = new SortedDictionary(StringComparer.Ordinal); + foreach (var record in records) + { + foreach (var tick in record.Ticks) + { + if (!longest.TryGetValue(tick.Kind, out var current) || tick.Seconds > current) + longest[tick.Kind] = tick.Seconds; + } + } + foreach (var pair in longest) summary.LongestSeconds[pair.Key] = pair.Value; + return summary; + } + + private static List Marks(IReadOnlyList records) + { + var firsts = new Dictionary>(StringComparer.Ordinal); + var order = new List(); + foreach (var record in records) + { + var seen = new HashSet(StringComparer.Ordinal); + foreach (var mark in record.Marks) + { + if (!seen.Add(mark.Name)) continue; + if (!firsts.TryGetValue(mark.Name, out var list)) + { + firsts[mark.Name] = list = new List(); + order.Add(mark.Name); + } + list.Add(mark.Time); + } + } + + return order.Select(name => new MarkResult + { + Name = name, + Bots = firsts[name].Count, + FirstSeconds = Percentile(Sorted(firsts[name]), 0.5), + }).ToList(); + } + + private static List Explains(IReadOnlyList records, List order) + { + var counts = new Dictionary, int>(); + var firstSeen = new List>(); + foreach (var record in records) + { + foreach (var explain in record.Explains.Distinct()) + { + if (!counts.ContainsKey(explain)) + { + counts[explain] = 0; + firstSeen.Add(explain); + } + counts[explain]++; + } + } + + int StageIndex(string id) + { + var i = order.FindIndex(s => s.Id == id); + return i < 0 ? int.MaxValue : i; + } + + return firstSeen + .Select((e, i) => new { Explain = e, Seen = i }) + .OrderBy(e => StageIndex(e.Explain.Key)) + .ThenByDescending(e => counts[e.Explain]) + .ThenBy(e => e.Seen) + .Select(e => new ExplainResult { Stage = e.Explain.Key, Text = e.Explain.Value, Bots = counts[e.Explain] }) + .ToList(); + } + + private static List Problems(IReadOnlyList records) + { + var problems = new List(); + + var errors = records.Where(r => r.Error != null).GroupBy(r => r.Error!, StringComparer.Ordinal); + foreach (var group in errors.OrderByDescending(g => g.Count()).ThenBy(g => g.Key, StringComparer.Ordinal)) + problems.Add(new ResultProblem { Kind = "error", Message = group.Key, Bots = group.Count() }); + + var timedOut = records.Count(r => !r.Finished && r.Error is null); + if (timedOut > 0) + problems.Add(new ResultProblem { Kind = "unfinished", Message = "Still playing at the time cap.", Bots = timedOut }); + + var missing = records.SelectMany(r => r.MissingOutcomes.Select(key => key)) + .GroupBy(key => key, StringComparer.Ordinal) + .OrderByDescending(g => g.Count()).ThenBy(g => g.Key, StringComparer.Ordinal); + foreach (var group in missing) + problems.Add(new ResultProblem { Kind = "missingOutcome", Message = group.Key, Bots = group.Count() }); + + return problems; + } + } +} diff --git a/Datra.Lab/Scenarios/Scenario.cs b/Datra.Lab/Scenarios/Scenario.cs new file mode 100644 index 0000000..4ae7890 --- /dev/null +++ b/Datra.Lab/Scenarios/Scenario.cs @@ -0,0 +1,33 @@ +#nullable enable +using System; +using System.Collections.Generic; + +namespace Datra.Lab +{ + /// + /// A variant to try: the baseline data plus the knobs that were moved, and how the bots are + /// run. It records only what differs from the baseline, so it stays small enough to save, + /// diff and put in a link. + /// + public sealed class Scenario + { + public string Name { get; set; } = string.Empty; + + /// Knob id → value, for the knobs that are off their baseline. + public Dictionary Changes { get; set; } = + new Dictionary(StringComparer.Ordinal); + + /// Number of bots. Null uses the lab's default. + public int? Bots { get; set; } + + /// Base seed. Null uses the lab's default. + public int? Seed { get; set; } + + /// Bot policy. Null uses the lab's default. + public string? Policy { get; set; } + + /// Policy parameter id → value, for the ones that differ from their defaults. + public Dictionary PolicyParams { get; set; } = + new Dictionary(StringComparer.Ordinal); + } +} diff --git a/Datra.Lab/Scenarios/Snapshots.cs b/Datra.Lab/Scenarios/Snapshots.cs new file mode 100644 index 0000000..c250cca --- /dev/null +++ b/Datra.Lab/Scenarios/Snapshots.cs @@ -0,0 +1,128 @@ +#nullable enable +using System; +using System.Collections.Generic; +using System.IO; +using System.Linq; +using System.Text.Json; +using System.Text.RegularExpressions; +using System.Threading.Tasks; + +namespace Datra.Lab +{ + /// + /// A named, frozen scenario together with the result it gave at the time. The result is + /// kept so "the picture we looked at" survives later changes to the data or the simulator. + /// + public sealed class LabSnapshot + { + public string Name { get; set; } = string.Empty; + public DateTimeOffset CreatedAtUtc { get; set; } + + /// Hash of the baseline data the result was computed from. + public string BaselineHash { get; set; } = string.Empty; + + public Scenario Scenario { get; set; } = new Scenario(); + public LabResult Result { get; set; } = new LabResult(); + } + + /// The listing entry for a snapshot: enough to pick one without loading its result. + public sealed class SnapshotInfo + { + public string Name { get; set; } = string.Empty; + public DateTimeOffset CreatedAtUtc { get; set; } + public string BaselineHash { get; set; } = string.Empty; + public int ChangedKnobs { get; set; } + } + + public interface ISnapshotStore + { + Task> ListAsync(); + Task LoadAsync(string name); + Task SaveAsync(LabSnapshot snapshot); + } + + /// + /// Snapshots as {name}.json files in one directory. Plain indented JSON, meant to be + /// committed next to the game's data. + /// + public sealed class FileSnapshotStore : ISnapshotStore + { + // Letters, digits, space and a few separators. No path characters, no leading dot. + private static readonly Regex ValidName = new Regex(@"^[\p{L}\p{N}][\p{L}\p{N} ._+\-]{0,79}$", RegexOptions.CultureInvariant); + + private readonly string _directory; + + public FileSnapshotStore(string directory) + { + if (string.IsNullOrWhiteSpace(directory)) throw new ArgumentException("A directory is required.", nameof(directory)); + _directory = Path.GetFullPath(directory); + } + + public string Directory => _directory; + + public static bool IsValidName(string? name) => + !string.IsNullOrEmpty(name) && ValidName.IsMatch(name) && !name!.Contains("..") && !name.EndsWith(".", StringComparison.Ordinal); + + public Task> ListAsync() + { + var list = new List(); + if (System.IO.Directory.Exists(_directory)) + { + foreach (var file in System.IO.Directory.GetFiles(_directory, "*.json")) + { + try + { + var snapshot = LabJson.Deserialize(File.ReadAllText(file)); + if (snapshot is null) continue; + list.Add(new SnapshotInfo + { + Name = Path.GetFileNameWithoutExtension(file), + CreatedAtUtc = snapshot.CreatedAtUtc, + BaselineHash = snapshot.BaselineHash, + ChangedKnobs = snapshot.Scenario?.Changes?.Count ?? 0, + }); + } + catch (JsonException) + { + // Not a snapshot (or a hand-edit gone wrong): leave it out of the list. + } + } + } + + IReadOnlyList ordered = list + .OrderByDescending(s => s.CreatedAtUtc) + .ThenBy(s => s.Name, StringComparer.Ordinal) + .ToList(); + return Task.FromResult(ordered); + } + + public Task LoadAsync(string name) + { + var path = PathFor(name); + if (!File.Exists(path)) return Task.FromResult(null); + var snapshot = LabJson.Deserialize(File.ReadAllText(path)); + if (snapshot != null) snapshot.Name = name; + return Task.FromResult(snapshot); + } + + public Task SaveAsync(LabSnapshot snapshot) + { + if (snapshot is null) throw new ArgumentNullException(nameof(snapshot)); + var path = PathFor(snapshot.Name); + System.IO.Directory.CreateDirectory(_directory); + File.WriteAllText(path, LabJson.Serialize(snapshot, indented: true)); + return Task.CompletedTask; + } + + private string PathFor(string name) + { + if (!IsValidName(name)) + { + throw new ArgumentException( + "A snapshot name is 1-80 letters, digits, spaces or . _ + - and starts with a letter or digit.", + nameof(name)); + } + return Path.Combine(_directory, name + ".json"); + } + } +} diff --git a/Datra.Lab/Simulation/BotRecord.cs b/Datra.Lab/Simulation/BotRecord.cs new file mode 100644 index 0000000..0ba4b44 --- /dev/null +++ b/Datra.Lab/Simulation/BotRecord.cs @@ -0,0 +1,143 @@ +#nullable enable +using System; +using System.Collections.Generic; +using System.Linq; + +namespace Datra.Lab +{ + /// A phase of the game the bot went through (a floor, a tier). Times are seconds of game time. + public sealed class StageRecord + { + internal StageRecord(string id, string label, double? targetSeconds, double start) + { + Id = id; Label = label; TargetSeconds = targetSeconds; StartSeconds = start; + } + + public string Id { get; } + public string Label { get; } + public double? TargetSeconds { get; } + public double StartSeconds { get; } + + /// When the bot left the stage. Null while it is still in it (the run stopped here). + public double? EndSeconds { get; internal set; } + } + + /// One slice of play: a run, a wait, a shop visit. + public readonly struct TickRecord + { + public TickRecord(double time, double seconds, double earned, string kind, int stage) + { + Time = time; Seconds = seconds; Earned = earned; Kind = kind; Stage = stage; + } + + /// Game time at the start of the tick. + public double Time { get; } + public double Seconds { get; } + public double Earned { get; } + public string Kind { get; } + /// Index into , or -1 before the first stage. + public int Stage { get; } + } + + public sealed class PurchaseRecord + { + internal PurchaseRecord(double time, string id, string label, double cost, string group, int stage) + { + Time = time; Id = id; Label = label; Cost = cost; Group = group; Stage = stage; + } + + public double Time { get; } + public string Id { get; } + public string Label { get; } + public double Cost { get; } + public string Group { get; } + public int Stage { get; } + } + + public sealed class MarkRecord + { + internal MarkRecord(double time, string name, double value, int stage) + { + Time = time; Name = name; Value = value; Stage = stage; + } + + public double Time { get; } + public string Name { get; } + public double Value { get; } + public int Stage { get; } + } + + /// How far through a stage the bot was at a moment: 0 on entry, 1 when it can leave. + public readonly struct ProgressPoint + { + public ProgressPoint(double time, int stage, double fraction) + { + Time = time; Stage = stage; Fraction = fraction; + } + + public double Time { get; } + public int Stage { get; } + public double Fraction { get; } + } + + /// Everything one bot wrote during . + public sealed class BotRecord + { + internal BotRecord(int bot, int seed) + { + Bot = bot; + Seed = seed; + } + + internal List StageList { get; } = new List(); + internal List TickList { get; } = new List(); + internal List PurchaseList { get; } = new List(); + internal List MarkList { get; } = new List(); + internal List ProgressList { get; } = new List(); + internal List> ExplainList { get; } = new List>(); + internal List MissingList { get; } = new List(); + + public int Bot { get; } + public int Seed { get; } + + /// Game time when the bot stopped. + public double TotalSeconds { get; internal set; } + + /// The bot played to the end: Play returned before the time cap and without an error. + public bool Finished { get; internal set; } + + /// Why the bot stopped early, when it threw. + public string? Error { get; internal set; } + + public IReadOnlyList Stages => StageList; + public IReadOnlyList Ticks => TickList; + public IReadOnlyList Purchases => PurchaseList; + public IReadOnlyList Marks => MarkList; + public IReadOnlyList Progress => ProgressList; + + /// Stage id and sentence, as passed to . + public IReadOnlyList> Explains => ExplainList; + + /// Physics keys the bot asked for that had no stored outcomes. + public IReadOnlyList MissingOutcomes => MissingList; + + public double TotalMinutes => TotalSeconds / 60.0; + public double TotalEarned => TickList.Sum(t => t.Earned); + + /// Game time of the first purchase, or NaN when the bot bought nothing. + public double FirstPurchaseSeconds => PurchaseList.Count > 0 ? PurchaseList[0].Time : double.NaN; + public double FirstPurchaseMinutes => FirstPurchaseSeconds / 60.0; + + /// Length of the longest tick of (any kind when null). + public double LongestTickSeconds(string? kind = null) + { + var longest = 0.0; + foreach (var tick in TickList) + { + if (kind != null && !string.Equals(tick.Kind, kind, StringComparison.Ordinal)) continue; + if (tick.Seconds > longest) longest = tick.Seconds; + } + return longest; + } + } +} diff --git a/Datra.Lab/Simulation/BotRunner.cs b/Datra.Lab/Simulation/BotRunner.cs new file mode 100644 index 0000000..6070e40 --- /dev/null +++ b/Datra.Lab/Simulation/BotRunner.cs @@ -0,0 +1,83 @@ +#nullable enable +using System; +using System.Collections.Generic; +using System.Threading; +using System.Threading.Tasks; +using Datra.Interfaces; + +namespace Datra.Lab +{ + /// + /// Plays a batch of bots through a simulator. Bots run in parallel, but each has its own + /// seed and its own , and the records come back in bot order, so the + /// result does not depend on scheduling. + /// + public static class BotRunner + { + public static IReadOnlyList Run( + ISimulator simulator, + TContext data, + RunSettings settings, + IOutcomeReader? outcomes = null, + CancellationToken cancellationToken = default) + where TContext : class, IDataContext + { + if (simulator is null) throw new ArgumentNullException(nameof(simulator)); + if (data is null) throw new ArgumentNullException(nameof(data)); + if (settings is null) throw new ArgumentNullException(nameof(settings)); + if (settings.Bots < 1) throw new ArgumentOutOfRangeException(nameof(settings), "At least one bot is needed."); + + var records = new BotRecord[settings.Bots]; + var parallel = new ParallelOptions + { + CancellationToken = cancellationToken, + MaxDegreeOfParallelism = settings.MaxParallelism > 0 ? settings.MaxParallelism : Environment.ProcessorCount, + }; + + Parallel.For(0, settings.Bots, parallel, bot => + { + records[bot] = Play(simulator, data, settings, bot, outcomes); + }); + + return records; + } + + /// + /// Play one bot of a batch on its own. It gets the seed it would have in the batch, so + /// its record is the same as the one returns at that index. + /// + public static BotRecord RunOne( + ISimulator simulator, + TContext data, + RunSettings settings, + int bot, + IOutcomeReader? outcomes = null) + where TContext : class, IDataContext + { + if (simulator is null) throw new ArgumentNullException(nameof(simulator)); + if (data is null) throw new ArgumentNullException(nameof(data)); + if (settings is null) throw new ArgumentNullException(nameof(settings)); + if (bot < 0) throw new ArgumentOutOfRangeException(nameof(bot)); + return Play(simulator, data, settings, bot, outcomes); + } + + private static BotRecord Play( + ISimulator simulator, TContext data, RunSettings settings, int bot, IOutcomeReader? outcomes) + where TContext : class, IDataContext + { + var run = new SimRun(bot, SimRandom.Derive(settings.Seed, bot), settings, outcomes); + Exception? error = null; + try + { + simulator.Play(data, run); + } + catch (Exception ex) + { + // One bot failing (a missing physics key, a bug in the simulator) is reported + // with the result; it does not take the other bots down. + error = ex; + } + return run.Complete(error); + } + } +} diff --git a/Datra.Lab/Simulation/ISimulator.cs b/Datra.Lab/Simulation/ISimulator.cs new file mode 100644 index 0000000..8183fcd --- /dev/null +++ b/Datra.Lab/Simulation/ISimulator.cs @@ -0,0 +1,20 @@ +#nullable enable +using Datra.Interfaces; + +namespace Datra.Lab +{ + /// + /// The one class a game writes: how a single bot plays the game from start to finish. + /// + /// + /// is called once per bot, from several threads at once, against + /// one shared . Keep the simulator stateless and treat the + /// data as read-only. + /// All randomness must come from : two calls with the same + /// and the same data must write the same records. + /// + public interface ISimulator where TContext : class, IDataContext + { + void Play(TContext data, SimRun run); + } +} diff --git a/Datra.Lab/Simulation/RunSettings.cs b/Datra.Lab/Simulation/RunSettings.cs new file mode 100644 index 0000000..ffa711f --- /dev/null +++ b/Datra.Lab/Simulation/RunSettings.cs @@ -0,0 +1,35 @@ +#nullable enable +using System; +using System.Collections.Generic; + +namespace Datra.Lab +{ + /// How a batch of bots is run. Part of a scenario, not of the data. + public sealed class RunSettings + { + /// Number of bots. + public int Bots { get; set; } = 40; + + /// + /// Base seed. Bot i plays with (Seed, i), so two + /// scenarios run with the same seed face the same luck and differ only by their knobs. + /// + public int Seed { get; set; } = 1; + + /// What the bot buys and when. The simulator decides what each name means. + public string Policy { get; set; } = "default"; + + /// Numbers the policy is tuned by (skill, seconds spent between runs). + public Dictionary PolicyParams { get; set; } = + new Dictionary(StringComparer.Ordinal); + + /// Game-time cap per bot. A bot still playing at this point is reported as unfinished. + public double MaxSimSeconds { get; set; } = 12 * 3600; + + /// Hard stop against a simulator that never advances time. + public int MaxRecords { get; set; } = 2_000_000; + + /// Threads used for the bots. Zero means one per processor. + public int MaxParallelism { get; set; } + } +} diff --git a/Datra.Lab/Simulation/SimRandom.cs b/Datra.Lab/Simulation/SimRandom.cs new file mode 100644 index 0000000..e6eddbd --- /dev/null +++ b/Datra.Lab/Simulation/SimRandom.cs @@ -0,0 +1,60 @@ +#nullable enable +using System; +using System.Collections.Generic; + +namespace Datra.Lab +{ + /// + /// SplitMix64. The lab's only source of randomness: the same seed gives the same sequence + /// on every runtime and platform, which does not promise. + /// + public sealed class SimRandom + { + private ulong _state; + + public SimRandom(long seed) + { + _state = unchecked((ulong)seed); + } + + public ulong NextULong() + { + unchecked + { + _state += 0x9E3779B97F4A7C15UL; + var z = _state; + z = (z ^ (z >> 30)) * 0xBF58476D1CE4E5B9UL; + z = (z ^ (z >> 27)) * 0x94D049BB133111EBUL; + return z ^ (z >> 31); + } + } + + /// Uniform in [0, 1). + public double NextDouble() => (NextULong() >> 11) * (1.0 / 9007199254740992.0); + + /// Uniform integer in [0, ). + public int Next(int exclusiveMax) + { + if (exclusiveMax <= 0) throw new ArgumentOutOfRangeException(nameof(exclusiveMax)); + return (int)(NextDouble() * exclusiveMax); + } + + /// Uniform in [, ). + public double Range(double min, double max) => min + (max - min) * NextDouble(); + + public bool Chance(double probability) => NextDouble() < probability; + + public T Pick(IReadOnlyList items) + { + if (items is null || items.Count == 0) throw new ArgumentException("Nothing to pick from.", nameof(items)); + return items[Next(items.Count)]; + } + + /// The seed of bot in a run started from . + public static int Derive(int seed, int index) + { + var mixer = new SimRandom(unchecked(((long)seed << 32) ^ (uint)index)); + return (int)(mixer.NextULong() >> 33); + } + } +} diff --git a/Datra.Lab/Simulation/SimRun.cs b/Datra.Lab/Simulation/SimRun.cs new file mode 100644 index 0000000..cf3e33a --- /dev/null +++ b/Datra.Lab/Simulation/SimRun.cs @@ -0,0 +1,173 @@ +#nullable enable +using System; +using System.Collections.Generic; + +namespace Datra.Lab +{ + /// + /// What a simulator writes to while one bot plays: phases, ticks, purchases and marks. The + /// views are drawn from these records alone, so they need no knowledge of the game. + /// + public sealed class SimRun + { + private readonly RunSettings _settings; + private readonly IOutcomeReader? _outcomes; + private readonly BotRecord _record; + private double _clock; + private int _records; + + internal SimRun(int bot, int seed, RunSettings settings, IOutcomeReader? outcomes) + { + _settings = settings; + _outcomes = outcomes; + _record = new BotRecord(bot, seed); + Seed = seed; + Random = new SimRandom(seed); + } + + internal BotRecord Record => _record; + + /// This bot's seed. The same seed and data must produce the same records. + public int Seed { get; } + + /// The bot's index in the batch. + public int Bot => _record.Bot; + + /// Runtime-independent random numbers, seeded from . + public SimRandom Random { get; } + + /// The policy chosen for this scenario. + public string Policy => _settings.Policy; + + /// A policy parameter, or when the scenario does not set it. + public double Param(string name, double fallback = 0) => + _settings.PolicyParams.TryGetValue(name, out var value) ? value : fallback; + + /// Game time so far, in seconds. + public double Elapsed => _clock; + + /// + /// The bot has played past the time cap. A simulator loops on !run.OutOfTime so a + /// scenario that can never finish (zero earnings) still returns. + /// + public bool OutOfTime => _clock >= _settings.MaxSimSeconds; + + /// + /// Enter a phase (a floor, a tier). The previous phase ends now. Entering the phase the + /// bot is already in does nothing. + /// + /// How long the phase is meant to take, for the target line. + public void Stage(string id, double? targetSeconds = null, string? label = null) + { + if (string.IsNullOrEmpty(id)) throw new ArgumentException("A stage needs an id.", nameof(id)); + var stages = _record.StageList; + if (stages.Count > 0) + { + var current = stages[stages.Count - 1]; + if (string.Equals(current.Id, id, StringComparison.Ordinal)) return; + current.EndSeconds = _clock; + } + + Count(); + stages.Add(new StageRecord(id, label ?? id, targetSeconds, _clock)); + _record.ProgressList.Add(new ProgressPoint(_clock, stages.Count - 1, 0)); + } + + /// + /// Report how far through the current phase the bot is, 0 to 1. Call it whenever that + /// changes — after earning and after spending, if spending sets the bot back. + /// + public void Progress(double fraction) + { + if (_record.StageList.Count == 0) return; + if (double.IsNaN(fraction)) fraction = 0; + Count(); + _record.ProgressList.Add(new ProgressPoint( + _clock, _record.StageList.Count - 1, Math.Max(0, Math.Min(1, fraction)))); + } + + /// Advance game time by one slice of play. + /// Length of the slice. + /// What the bot earned in it. + /// What the slice was: "run", "shop", a wait. + public void Tick(double seconds, double earned = 0, string kind = "run") + { + if (!(seconds >= 0)) throw new ArgumentOutOfRangeException(nameof(seconds), "A tick cannot run backwards."); + Count(); + _record.TickList.Add(new TickRecord(_clock, seconds, earned, kind ?? "run", _record.StageList.Count - 1)); + _clock += seconds; + } + + /// The bot bought something at the current game time. + /// Lane on the purchase timeline (account, floor device). + public void Purchase(string id, double cost, string? group = null, string? label = null) + { + Count(); + _record.PurchaseList.Add(new PurchaseRecord( + _clock, id, label ?? id, cost, group ?? string.Empty, _record.StageList.Count - 1)); + } + + /// Note a moment worth finding later: first intact bottle, first refill chain. + public void Mark(string name, double value = 1) + { + Count(); + _record.MarkList.Add(new MarkRecord(_clock, name, value, _record.StageList.Count - 1)); + } + + /// A reason only the game knows, attached to a phase ("bottles stop on the landing"). + public void Explain(string stage, string text) + { + if (string.IsNullOrWhiteSpace(text)) return; + _record.ExplainList.Add(new KeyValuePair(stage ?? string.Empty, text)); + } + + /// + /// Draw one stored physics outcome for , using this bot's random numbers. + /// + /// Nothing is stored for the key. + public T Outcome(PhysicsKey key) + { + if (TryOutcome(key, out var sample)) return sample; + throw new MissingOutcomeException(key); + } + + /// + /// Like , but returns false instead of throwing so the simulator + /// can fall back to an estimate. The missing key is reported with the result either way. + /// + public bool TryOutcome(PhysicsKey key, out T sample) + { + if (key is null) throw new ArgumentNullException(nameof(key)); + var pool = _outcomes?.Pool(key); + if (pool is null || pool.Count == 0) + { + if (!_record.MissingList.Contains(key.Text)) _record.MissingList.Add(key.Text); + sample = default!; + return false; + } + + sample = pool[Random.Next(pool.Count)]; + return true; + } + + internal BotRecord Complete(Exception? error) + { + _record.TotalSeconds = _clock; + _record.Error = error?.Message; + _record.Finished = error is null && !OutOfTime; + if (_record.Finished && _record.StageList.Count > 0) + _record.StageList[_record.StageList.Count - 1].EndSeconds = _clock; + return _record; + } + + private void Count() + { + if (++_records > _settings.MaxRecords) + { + throw new InvalidOperationException( + $"The simulator wrote more than {_settings.MaxRecords:N0} records for one bot. " + + "It is probably looping without advancing time; check run.OutOfTime in its loops."); + } + } + } +} diff --git a/Datra.sln b/Datra.sln index c63fd62..ec0368f 100644 --- a/Datra.sln +++ b/Datra.sln @@ -26,6 +26,12 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Datra.WebEditor.Tests", "Da EndProject Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Datra.WebEditor.Sample", "Datra.WebEditor.Sample\Datra.WebEditor.Sample.csproj", "{81F49D87-8577-44CC-A268-160300ADE8F9}" EndProject +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Datra.Lab", "Datra.Lab\Datra.Lab.csproj", "{B99BD750-1DC7-44C0-9547-F61C342DB4E4}" +EndProject +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Datra.Lab.Sample", "Datra.Lab.Sample\Datra.Lab.Sample.csproj", "{AFB139F6-1961-41D0-8219-5CB8DE3F232C}" +EndProject +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Datra.Lab.Tests", "Datra.Lab.Tests\Datra.Lab.Tests.csproj", "{EAA0914A-DEDC-4572-BFED-9C2763146EBC}" +EndProject Global GlobalSection(SolutionConfigurationPlatforms) = preSolution Debug|Any CPU = Debug|Any CPU @@ -192,6 +198,42 @@ Global {81F49D87-8577-44CC-A268-160300ADE8F9}.Release|x64.Build.0 = Release|Any CPU {81F49D87-8577-44CC-A268-160300ADE8F9}.Release|x86.ActiveCfg = Release|Any CPU {81F49D87-8577-44CC-A268-160300ADE8F9}.Release|x86.Build.0 = Release|Any CPU + {B99BD750-1DC7-44C0-9547-F61C342DB4E4}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {B99BD750-1DC7-44C0-9547-F61C342DB4E4}.Debug|Any CPU.Build.0 = Debug|Any CPU + {B99BD750-1DC7-44C0-9547-F61C342DB4E4}.Debug|x64.ActiveCfg = Debug|Any CPU + {B99BD750-1DC7-44C0-9547-F61C342DB4E4}.Debug|x64.Build.0 = Debug|Any CPU + {B99BD750-1DC7-44C0-9547-F61C342DB4E4}.Debug|x86.ActiveCfg = Debug|Any CPU + {B99BD750-1DC7-44C0-9547-F61C342DB4E4}.Debug|x86.Build.0 = Debug|Any CPU + {B99BD750-1DC7-44C0-9547-F61C342DB4E4}.Release|Any CPU.ActiveCfg = Release|Any CPU + {B99BD750-1DC7-44C0-9547-F61C342DB4E4}.Release|Any CPU.Build.0 = Release|Any CPU + {B99BD750-1DC7-44C0-9547-F61C342DB4E4}.Release|x64.ActiveCfg = Release|Any CPU + {B99BD750-1DC7-44C0-9547-F61C342DB4E4}.Release|x64.Build.0 = Release|Any CPU + {B99BD750-1DC7-44C0-9547-F61C342DB4E4}.Release|x86.ActiveCfg = Release|Any CPU + {B99BD750-1DC7-44C0-9547-F61C342DB4E4}.Release|x86.Build.0 = Release|Any CPU + {AFB139F6-1961-41D0-8219-5CB8DE3F232C}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {AFB139F6-1961-41D0-8219-5CB8DE3F232C}.Debug|Any CPU.Build.0 = Debug|Any CPU + {AFB139F6-1961-41D0-8219-5CB8DE3F232C}.Debug|x64.ActiveCfg = Debug|Any CPU + {AFB139F6-1961-41D0-8219-5CB8DE3F232C}.Debug|x64.Build.0 = Debug|Any CPU + {AFB139F6-1961-41D0-8219-5CB8DE3F232C}.Debug|x86.ActiveCfg = Debug|Any CPU + {AFB139F6-1961-41D0-8219-5CB8DE3F232C}.Debug|x86.Build.0 = Debug|Any CPU + {AFB139F6-1961-41D0-8219-5CB8DE3F232C}.Release|Any CPU.ActiveCfg = Release|Any CPU + {AFB139F6-1961-41D0-8219-5CB8DE3F232C}.Release|Any CPU.Build.0 = Release|Any CPU + {AFB139F6-1961-41D0-8219-5CB8DE3F232C}.Release|x64.ActiveCfg = Release|Any CPU + {AFB139F6-1961-41D0-8219-5CB8DE3F232C}.Release|x64.Build.0 = Release|Any CPU + {AFB139F6-1961-41D0-8219-5CB8DE3F232C}.Release|x86.ActiveCfg = Release|Any CPU + {AFB139F6-1961-41D0-8219-5CB8DE3F232C}.Release|x86.Build.0 = Release|Any CPU + {EAA0914A-DEDC-4572-BFED-9C2763146EBC}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {EAA0914A-DEDC-4572-BFED-9C2763146EBC}.Debug|Any CPU.Build.0 = Debug|Any CPU + {EAA0914A-DEDC-4572-BFED-9C2763146EBC}.Debug|x64.ActiveCfg = Debug|Any CPU + {EAA0914A-DEDC-4572-BFED-9C2763146EBC}.Debug|x64.Build.0 = Debug|Any CPU + {EAA0914A-DEDC-4572-BFED-9C2763146EBC}.Debug|x86.ActiveCfg = Debug|Any CPU + {EAA0914A-DEDC-4572-BFED-9C2763146EBC}.Debug|x86.Build.0 = Debug|Any CPU + {EAA0914A-DEDC-4572-BFED-9C2763146EBC}.Release|Any CPU.ActiveCfg = Release|Any CPU + {EAA0914A-DEDC-4572-BFED-9C2763146EBC}.Release|Any CPU.Build.0 = Release|Any CPU + {EAA0914A-DEDC-4572-BFED-9C2763146EBC}.Release|x64.ActiveCfg = Release|Any CPU + {EAA0914A-DEDC-4572-BFED-9C2763146EBC}.Release|x64.Build.0 = Release|Any CPU + {EAA0914A-DEDC-4572-BFED-9C2763146EBC}.Release|x86.ActiveCfg = Release|Any CPU + {EAA0914A-DEDC-4572-BFED-9C2763146EBC}.Release|x86.Build.0 = Release|Any CPU EndGlobalSection GlobalSection(SolutionProperties) = preSolution HideSolutionNode = FALSE diff --git a/Datra/Attributes/KnobAttribute.cs b/Datra/Attributes/KnobAttribute.cs new file mode 100644 index 0000000..9d17eb2 --- /dev/null +++ b/Datra/Attributes/KnobAttribute.cs @@ -0,0 +1,100 @@ +using System; + +namespace Datra.Attributes +{ + /// + /// Which layer of a balance simulation a knob reaches. + /// + public enum KnobLayer + { + /// Re-pricing only: the simulator can be re-run immediately. + Economy, + + /// + /// Changes the outcome of a physics run, so stored outcomes no longer apply and have to + /// be recomputed. Tools show these read-only until they can recompute. + /// + Physics + } + + /// + /// How a knob value is written to the field it points at. + /// + public enum KnobApply + { + /// The field becomes the knob value. + Set, + + /// The field is multiplied by the knob value. The knob rests at 1. + Scale, + + /// The knob value is added to the field. The knob rests at 0. + Offset + } + + /// + /// Marks a numeric property as a tuning knob: a named value with a unit and a range that a + /// balance tool (Datra.Lab) can move without editing the data file. + /// + /// + /// On a [SingleData] type the knob addresses that one object. On a + /// [TableData] type it addresses every row unless or + /// narrows it. + /// The attribute may be repeated to expose the same column as several knobs, one per + /// . + /// + /// + /// + /// [Knob("Pellet value", Group = "Rewards", Unit = "coins", Min = 0.5, Max = 5, Step = 0.1)] + /// public float PelletValue { get; set; } = 1f; + /// + /// [Knob("Base push", Group = "Hand", Unit = "m/s", Min = 0.5, Max = 1.4, + /// Layer = KnobLayer.Physics, Row = "push-strength")] + /// public float Base { get; set; } + /// + /// + [AttributeUsage(AttributeTargets.Property, AllowMultiple = true, Inherited = true)] + public sealed class KnobAttribute : Attribute + { + public KnobAttribute(string label) + { + Label = label ?? throw new ArgumentNullException(nameof(label)); + } + + /// The name shown to the person turning the knob. + public string Label { get; } + + /// Heading the knob is listed under. + public string Group { get; set; } = string.Empty; + + /// Unit shown after the value, e.g. "coins/step". + public string Unit { get; set; } = string.Empty; + + /// One line on what the value does. + public string Hint { get; set; } = string.Empty; + + /// Lower bound. (the default) lets the tool pick one. + public double Min { get; set; } = double.NaN; + + /// Upper bound. (the default) lets the tool pick one. + public double Max { get; set; } = double.NaN; + + /// Slider step. Zero (the default) lets the tool pick one. + public double Step { get; set; } + + /// Whether moving the knob invalidates stored physics outcomes. + public KnobLayer Layer { get; set; } = KnobLayer.Economy; + + /// Table data only: the Id of the one row this knob addresses. Empty means every row. + public string Row { get; set; } = string.Empty; + + /// + /// Table data only: expand into one knob per row, labelled "{Label} · {row Id}". + /// Ignored when is set. + /// + public bool EachRow { get; set; } + + /// How the value is written to the field. + public KnobApply Apply { get; set; } = KnobApply.Set; + } +} diff --git a/Datra/Attributes/KnobAttribute.cs.meta b/Datra/Attributes/KnobAttribute.cs.meta new file mode 100644 index 0000000..14c769d --- /dev/null +++ b/Datra/Attributes/KnobAttribute.cs.meta @@ -0,0 +1,2 @@ +fileFormatVersion: 2 +guid: 360e04c66a394821a48b614fd6e708af \ No newline at end of file From d5065a50b87bab69aa1eca52ee3174f7bfc38014 Mon Sep 17 00:00:00 2001 From: penspanic Date: Wed, 30 Sep 2026 19:41:58 +0900 Subject: [PATCH 2/3] feat: host the balance lab in the web editor - Datra.WebEditor.Server: AddDatraLab() and MapDatraLab() (/api/datra/lab/schema, /run, /snapshots). The lab reads the baseline through the container's IRawDataProvider and refreshes it when the table editor saves or reloads. - Datra.WebEditor: , a host for framework-free JavaScript view modules (SVG): a knob panel built from the schema, time per stage, progression, purchase timeline, each with the comparison (saved data or a snapshot) drawn behind the scenario. The modules take a source object, so a standalone export can feed them later. - Datra.WebEditor.Sample: /lab runs the toy game end to end. - Endpoint round-trip tests on an in-memory server. Co-Authored-By: Claude Opus 5.5 --- .../Components/Pages/Home.razor | 3 + .../Components/Pages/Lab.razor | 17 + .../Datra.WebEditor.Sample.csproj | 2 + Datra.WebEditor.Sample/Program.cs | 17 + Datra.WebEditor.Sample/README.md | 8 + .../Datra.WebEditor.Server.csproj | 1 + Datra.WebEditor.Server/DatraLabEndpoints.cs | 113 +++++ .../DatraLabServiceCollectionExtensions.cs | 80 ++++ Datra.WebEditor.Server/README.md | 23 +- .../Datra.WebEditor.Tests.csproj | 3 + Datra.WebEditor.Tests/LabEndpointTests.cs | 278 +++++++++++++ Datra.WebEditor/Components/DatraLab.razor | 45 ++ Datra.WebEditor/README.md | 13 + Datra.WebEditor/wwwroot/lab/datra-lab.css | 175 ++++++++ Datra.WebEditor/wwwroot/lab/datra-lab.js | 390 ++++++++++++++++++ Datra.WebEditor/wwwroot/lab/lab-knobs.js | 80 ++++ Datra.WebEditor/wwwroot/lab/lab-text.js | 189 +++++++++ Datra.WebEditor/wwwroot/lab/lab-views.js | 297 +++++++++++++ 18 files changed, 1733 insertions(+), 1 deletion(-) create mode 100644 Datra.WebEditor.Sample/Components/Pages/Lab.razor create mode 100644 Datra.WebEditor.Server/DatraLabEndpoints.cs create mode 100644 Datra.WebEditor.Server/DatraLabServiceCollectionExtensions.cs create mode 100644 Datra.WebEditor.Tests/LabEndpointTests.cs create mode 100644 Datra.WebEditor/Components/DatraLab.razor create mode 100644 Datra.WebEditor/wwwroot/lab/datra-lab.css create mode 100644 Datra.WebEditor/wwwroot/lab/datra-lab.js create mode 100644 Datra.WebEditor/wwwroot/lab/lab-knobs.js create mode 100644 Datra.WebEditor/wwwroot/lab/lab-text.js create mode 100644 Datra.WebEditor/wwwroot/lab/lab-views.js diff --git a/Datra.WebEditor.Sample/Components/Pages/Home.razor b/Datra.WebEditor.Sample/Components/Pages/Home.razor index 076b49b..0fce8af 100644 --- a/Datra.WebEditor.Sample/Components/Pages/Home.razor +++ b/Datra.WebEditor.Sample/Components/Pages/Home.razor @@ -12,6 +12,7 @@ Edits write to a scratch copy of Datra.SampleData/Resources under your OS temp directory — your repo stays clean. + Balance lab →
@@ -75,6 +76,8 @@ .sample-shell__sub { font-size: 11px; color: var(--datra-text-muted); font-family: var(--datra-font-mono); } .sample-shell__hint { font-size: 11px; color: var(--datra-text-subtle); } .sample-shell__hint code { font-family: var(--datra-font-mono); background: var(--datra-bg); padding: 1px 6px; border-radius: 4px; } + .sample-shell__link { font-size: 12px; color: var(--datra-accent); text-decoration: none; white-space: nowrap; } + .sample-shell__link:hover { color: var(--datra-accent-hover); } .sample-shell__body { flex: 1; min-height: 0; diff --git a/Datra.WebEditor.Sample/Components/Pages/Lab.razor b/Datra.WebEditor.Sample/Components/Pages/Lab.razor new file mode 100644 index 0000000..1ce2300 --- /dev/null +++ b/Datra.WebEditor.Sample/Components/Pages/Lab.razor @@ -0,0 +1,17 @@ +@page "/lab" + +Datra.Lab — Sample + +@* MainLayout pins the page to the viewport for the table editor; the lab is a long page, so it scrolls here. *@ +
+ +
+ +@code { + /// Language of the lab's own text: /lab?lang=ko. + [SupplyParameterFromQuery(Name = "lang")] public string? Lang { get; set; } +} + + diff --git a/Datra.WebEditor.Sample/Datra.WebEditor.Sample.csproj b/Datra.WebEditor.Sample/Datra.WebEditor.Sample.csproj index a11bb15..1440588 100644 --- a/Datra.WebEditor.Sample/Datra.WebEditor.Sample.csproj +++ b/Datra.WebEditor.Sample/Datra.WebEditor.Sample.csproj @@ -13,6 +13,8 @@ + + diff --git a/Datra.WebEditor.Sample/Program.cs b/Datra.WebEditor.Sample/Program.cs index bcc449b..5b61dd0 100644 --- a/Datra.WebEditor.Sample/Program.cs +++ b/Datra.WebEditor.Sample/Program.cs @@ -1,4 +1,6 @@ using Datra.Interfaces; +using Datra.Lab.Sample; +using Datra.Lab.Sample.Generated; using Datra.SampleData.Generated; using Datra.Serializers; using Datra.WebEditor.Extensions; @@ -26,12 +28,27 @@ builder.Services.AddDatraWebEditor(opt => opt.DataContextType = typeof(GameDataContext)); +// Balance lab (/lab): a toy incremental game tuned through knobs. Its three YAML files are +// staged next to the editor's sample data, so the one IRawDataProvider above serves both. +DescentData.WriteTo(scratchPath.Path); +builder.Services.AddDatraLab((services, lab) => +{ + DescentLab.Configure(lab); + lab.SnapshotDirectory(Path.Combine(scratchPath.Path, "lab-snapshots")); + + // Stand-in for a game's overnight physics batch: roll the outcome pools once, from the saved data. + var saved = new DescentContext(services.GetRequiredService()); + saved.LoadAllAsync().GetAwaiter().GetResult(); + lab.Outcomes = DescentPhysics.Bake(saved); +}); + var app = builder.Build(); app.UseStaticFiles(); app.UseAntiforgery(); app.MapDatraEditor(); +app.MapDatraLab(); app.MapRazorComponents() .AddInteractiveServerRenderMode(); diff --git a/Datra.WebEditor.Sample/README.md b/Datra.WebEditor.Sample/README.md index a6f3481..83ed24c 100644 --- a/Datra.WebEditor.Sample/README.md +++ b/Datra.WebEditor.Sample/README.md @@ -24,6 +24,14 @@ directory; Revert drops pending edits. Single, asset, and localisation repositories are recognised by the data context but hidden until the editor grows dedicated views for them. +## Balance lab + + (or `/lab?lang=ko`) shows [Datra.Lab](../docs/LAB.md) on a toy +incremental game from `Datra.Lab.Sample`: floors with a fare, a fare box that is also the +wallet, upgrades. Move a knob and 40 bots replay the game; the saved data is drawn in grey +behind the new result. Its three YAML files are staged into the same scratch directory, and +snapshots go to `lab-snapshots/` inside it. + ## What happens on disk Your repo stays clean. On every launch, `SampleResourceStager` copies diff --git a/Datra.WebEditor.Server/Datra.WebEditor.Server.csproj b/Datra.WebEditor.Server/Datra.WebEditor.Server.csproj index bc6301e..33790a0 100644 --- a/Datra.WebEditor.Server/Datra.WebEditor.Server.csproj +++ b/Datra.WebEditor.Server/Datra.WebEditor.Server.csproj @@ -24,6 +24,7 @@ + diff --git a/Datra.WebEditor.Server/DatraLabEndpoints.cs b/Datra.WebEditor.Server/DatraLabEndpoints.cs new file mode 100644 index 0000000..57c8b9d --- /dev/null +++ b/Datra.WebEditor.Server/DatraLabEndpoints.cs @@ -0,0 +1,113 @@ +#nullable enable +using System; +using System.Text.Json; +using System.Threading; +using System.Threading.Tasks; +using Datra.Lab; +using Microsoft.AspNetCore.Builder; +using Microsoft.AspNetCore.Http; +using Microsoft.AspNetCore.Routing; + +namespace Datra.WebEditor.Server; + +/// +/// HTTP surface of the balance lab. The lab screen (<DatraLab />) is drawn by +/// JavaScript view modules that talk to these endpoints, so the same modules can later read a +/// result baked into an exported page instead. +/// +public static class DatraLabEndpoints +{ + /// + /// Map the lab endpoints under (default: /api/datra/lab). + /// Requires AddDatraLab. + /// + /// The endpoint group, in case the consumer wants to chain authorisation policies. + public static RouteGroupBuilder MapDatraLab(this IEndpointRouteBuilder app, string basePath = "/api/datra/lab") + { + if (app is null) throw new ArgumentNullException(nameof(app)); + var group = app.MapGroup(basePath).WithTags("Datra Lab"); + + group.MapGet("/schema", async (ILabEngine lab, CancellationToken ct) => + Json(await lab.GetSchemaAsync(ct))); + + group.MapPost("/run", async (HttpRequest request, ILabEngine lab, CancellationToken ct) => + { + var (scenario, problem) = await ReadAsync(request, ct); + if (scenario is null) return problem!; + + try + { + return Json(await lab.RunAsync(scenario, ct)); + } + catch (ScenarioException ex) + { + return Error(StatusCodes.Status400BadRequest, ex.Message); + } + }); + + group.MapGet("/snapshots", async (ILabEngine lab) => + lab.Snapshots is null + ? Error(StatusCodes.Status404NotFound, "Snapshots are off for this lab.") + : Json(await lab.Snapshots.ListAsync())); + + group.MapGet("/snapshots/{name}", async (string name, ILabEngine lab) => + { + if (lab.Snapshots is null) return Error(StatusCodes.Status404NotFound, "Snapshots are off for this lab."); + if (!FileSnapshotStore.IsValidName(name)) return Error(StatusCodes.Status400BadRequest, "Not a snapshot name."); + + var snapshot = await lab.Snapshots.LoadAsync(name); + return snapshot is null + ? Error(StatusCodes.Status404NotFound, $"No snapshot named '{name}'.") + : Json(snapshot); + }); + + group.MapPost("/snapshots", async (HttpRequest request, ILabEngine lab, CancellationToken ct) => + { + if (lab.Snapshots is null) return Error(StatusCodes.Status404NotFound, "Snapshots are off for this lab."); + + var (body, problem) = await ReadAsync(request, ct); + if (body is null) return problem!; + + try + { + return Json(await lab.SaveSnapshotAsync(body.Name, body.Scenario ?? new Scenario(), ct)); + } + catch (ScenarioException ex) + { + return Error(StatusCodes.Status400BadRequest, ex.Message); + } + }); + + return group; + } + + /// Body of POST /snapshots: the scenario to freeze and the name to keep it under. + public sealed class SaveSnapshotRequest + { + public string Name { get; set; } = string.Empty; + public Scenario? Scenario { get; set; } + } + + // The lab has its own JSON shape (LabJson). Reading and writing with it here keeps the + // documents identical whatever JSON options the host application configured. + private static IResult Json(T value) => Results.Json(value, LabJson.Options); + + private static IResult Error(int status, string message) => + Results.Json(new { error = message }, LabJson.Options, statusCode: status); + + private static async Task<(T? Value, IResult? Problem)> ReadAsync(HttpRequest request, CancellationToken ct) + where T : class + { + try + { + var value = await JsonSerializer.DeserializeAsync(request.Body, LabJson.Options, ct); + return value is null + ? (null, Error(StatusCodes.Status400BadRequest, "The request body is empty.")) + : (value, null); + } + catch (JsonException ex) + { + return (null, Error(StatusCodes.Status400BadRequest, "The request body is not valid JSON: " + ex.Message)); + } + } +} diff --git a/Datra.WebEditor.Server/DatraLabServiceCollectionExtensions.cs b/Datra.WebEditor.Server/DatraLabServiceCollectionExtensions.cs new file mode 100644 index 0000000..d9e7a1f --- /dev/null +++ b/Datra.WebEditor.Server/DatraLabServiceCollectionExtensions.cs @@ -0,0 +1,80 @@ +#nullable enable +using System; +using System.Threading.Tasks; +using Datra.Interfaces; +using Datra.Lab; +using Datra.WebEditor.Services; +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.DependencyInjection.Extensions; + +namespace Datra.WebEditor.Server; + +/// +/// DI extension methods for hosting the balance lab (Datra.Lab) next to the web editor. +/// +public static class DatraLabServiceCollectionExtensions +{ + /// + /// Register the lab for one data context and one simulator. The container must be able to + /// resolve an : the lab reads the baseline data through it + /// and never writes to it. + /// + /// + /// + /// builder.Services.AddDatraLab<GameDataContext, GameSim>(lab => lab.SnapshotDirectory("lab/snapshots")); + /// app.MapDatraLab(); + /// + /// + public static IServiceCollection AddDatraLab( + this IServiceCollection services, + Action>? configure = null) + where TContext : class, IDataContext + where TSimulator : class, ISimulator + => services.AddDatraLab((_, options) => configure?.Invoke(options)); + + /// + /// As , + /// for options that need other services (stored physics outcomes, a configured path). + /// + public static IServiceCollection AddDatraLab( + this IServiceCollection services, + Action> configure) + where TContext : class, IDataContext + where TSimulator : class, ISimulator + { + if (services is null) throw new ArgumentNullException(nameof(services)); + if (configure is null) throw new ArgumentNullException(nameof(configure)); + + // One simulator instance plays every bot, on several threads: it has to be stateless. + services.TryAddSingleton(); + + services.AddSingleton(provider => + { + var source = provider.GetService() + ?? throw new InvalidOperationException( + "AddDatraLab needs an IRawDataProvider in the container to read the baseline data from. " + + "Register the provider your data context is built on, or construct LabEngine " + + "yourself and register it as ILabEngine."); + + var options = new LabOptions(); + configure(provider, options); + + var engine = new LabEngine(source, provider.GetRequiredService(), options); + + // The lab caches the baseline files. When the table editor saves or reloads, the + // baseline is whatever is on disk now. + if (provider.GetService() is { } notifier) + { + notifier.Changed += _ => + { + engine.InvalidateBaseline(); + return Task.CompletedTask; + }; + } + + return engine; + }); + + return services; + } +} diff --git a/Datra.WebEditor.Server/README.md b/Datra.WebEditor.Server/README.md index 19ffe7c..a7acf19 100644 --- a/Datra.WebEditor.Server/README.md +++ b/Datra.WebEditor.Server/README.md @@ -32,6 +32,27 @@ Endpoints: `typeName` accepts both the short and fully-qualified CLR type name. -The endpoints are deliberately minimal — they're for external trigger scenarios (CI bots, CLI +## Balance lab + +`AddDatraLab` registers the lab engine ([Datra.Lab](../docs/LAB.md)) for one data context and +one simulator; `MapDatraLab` exposes it to the `` screen: + +```csharp +builder.Services.AddDatraLab(lab => lab.SnapshotDirectory("lab/snapshots")); +app.MapDatraLab(); // → /api/datra/lab/{schema,run,snapshots} +``` + +| Method | Route | Purpose | +|--------|------------------------------------|-------------------------------------------------| +| GET | `/api/datra/lab/schema` | Knobs, policies, checks, defaults | +| POST | `/api/datra/lab/run` | Scenario in, aggregated bot result out | +| GET | `/api/datra/lab/snapshots` | Saved snapshots | +| POST | `/api/datra/lab/snapshots` | Run a scenario and store it with its result | +| GET | `/api/datra/lab/snapshots/{name}` | One stored scenario and result | + +The lab reads the baseline data through the `IRawDataProvider` in the container and never +writes to it. + +The editor endpoints are deliberately minimal — they're for external trigger scenarios (CI bots, CLI tools, remote reload from a co-running process). Day-to-day editing goes through the Blazor UI via DI, not HTTP. diff --git a/Datra.WebEditor.Tests/Datra.WebEditor.Tests.csproj b/Datra.WebEditor.Tests/Datra.WebEditor.Tests.csproj index 8824a69..ee85c4b 100644 --- a/Datra.WebEditor.Tests/Datra.WebEditor.Tests.csproj +++ b/Datra.WebEditor.Tests/Datra.WebEditor.Tests.csproj @@ -16,11 +16,14 @@ + + + runtime; build; native; contentfiles; analyzers; buildtransitive diff --git a/Datra.WebEditor.Tests/LabEndpointTests.cs b/Datra.WebEditor.Tests/LabEndpointTests.cs new file mode 100644 index 0000000..e174405 --- /dev/null +++ b/Datra.WebEditor.Tests/LabEndpointTests.cs @@ -0,0 +1,278 @@ +#nullable enable +using System; +using System.Collections.Generic; +using System.IO; +using System.Linq; +using System.Net; +using System.Net.Http; +using System.Text; +using System.Text.Json; +using System.Threading.Tasks; +using Datra.Interfaces; +using Datra.Lab; +using Datra.Lab.Sample; +using Datra.Lab.Sample.Generated; +using Datra.Providers; +using Datra.WebEditor.Server; +using Datra.WebEditor.Services; +using Microsoft.AspNetCore.Builder; +using Microsoft.AspNetCore.Hosting; +using Microsoft.AspNetCore.TestHost; +using Microsoft.Extensions.DependencyInjection; +using Xunit; + +namespace Datra.WebEditor.Tests; + +/// +/// The lab over HTTP, the way the JavaScript views use it: schema out, scenario in, result out, +/// snapshots saved and read back. +/// +public class LabEndpointTests +{ + /// A real ASP.NET Core pipeline on an in-memory server, over the toy game staged in a scratch directory. + private sealed class LabHost : IAsyncDisposable + { + private readonly string _root; + public string DataPath { get; } + public WebApplication App { get; } + public HttpClient Client { get; } + + private LabHost(string root, string dataPath, WebApplication app) + { + _root = root; + DataPath = dataPath; + App = app; + Client = app.GetTestClient(); + } + + public static async Task StartAsync(bool snapshots = true) + { + var root = Path.Combine(Path.GetTempPath(), "datra-webeditor-tests", Guid.NewGuid().ToString("N")); + var dataPath = DescentData.WriteTo(Path.Combine(root, "data")); + + var builder = WebApplication.CreateBuilder(); + builder.WebHost.UseTestServer(); + builder.Services.AddSingleton(new FileSystemRawDataProvider(dataPath)); + builder.Services.AddSingleton(); + builder.Services.AddDatraLab((services, lab) => + { + DescentLab.Configure(lab); + if (snapshots) lab.SnapshotDirectory(Path.Combine(root, "snapshots")); + + var saved = new DescentContext(services.GetRequiredService()); + saved.LoadAllAsync().GetAwaiter().GetResult(); + lab.Outcomes = DescentPhysics.Bake(saved); + }); + + var app = builder.Build(); + app.MapDatraLab(); + await app.StartAsync(); + return new LabHost(root, dataPath, app); + } + + public async Task<(HttpStatusCode Status, JsonElement Body)> GetAsync(string path) + { + using var response = await Client.GetAsync("/api/datra/lab" + path); + return (response.StatusCode, await ReadAsync(response)); + } + + public async Task<(HttpStatusCode Status, JsonElement Body)> PostAsync(string path, string json) + { + using var content = new StringContent(json, Encoding.UTF8, "application/json"); + using var response = await Client.PostAsync("/api/datra/lab" + path, content); + return (response.StatusCode, await ReadAsync(response)); + } + + public Dictionary ReadFiles() => + Directory.GetFiles(DataPath).ToDictionary(f => Path.GetFileName(f)!, File.ReadAllText); + + private static async Task ReadAsync(HttpResponseMessage response) + { + var text = await response.Content.ReadAsStringAsync(); + return text.Length == 0 ? default : JsonDocument.Parse(text).RootElement.Clone(); + } + + public async ValueTask DisposeAsync() + { + await App.DisposeAsync(); + try { Directory.Delete(_root, recursive: true); } catch { /* best-effort */ } + } + } + + /// The result without its wall-clock timing, for comparing two runs. + private static string WithoutTiming(JsonElement result) => + string.Join(",", result.EnumerateObject().Where(p => p.Name != "timing").Select(p => p.Name + ":" + p.Value.GetRawText())); + + [Fact] + public async Task Schema_describes_the_knobs_in_the_labs_own_json_shape() + { + await using var host = await LabHost.StartAsync(); + + var (status, schema) = await host.GetAsync("/schema"); + + Assert.Equal(HttpStatusCode.OK, status); + Assert.Equal("Descent · balance lab", schema.GetProperty("title").GetString()); + Assert.Equal("DescentContext", schema.GetProperty("context").GetString()); + + var knobs = schema.GetProperty("knobs").EnumerateArray().ToList(); + var step = knobs.Single(k => k.GetProperty("id").GetString() == "EconomyData.StepValue"); + Assert.Equal("Step value", step.GetProperty("label").GetString()); + Assert.Equal("coins/step", step.GetProperty("unit").GetString()); + Assert.Equal(5, step.GetProperty("baseline").GetDouble()); + // Enums travel as camelCase names, not numbers. + Assert.Equal("economy", step.GetProperty("layer").GetString()); + Assert.Equal("set", step.GetProperty("apply").GetString()); + Assert.Equal("Economy.yaml", step.GetProperty("source").GetProperty("file").GetString()); + + var glass = knobs.Single(k => k.GetProperty("id").GetString() == "EconomyData.GlassToughness"); + Assert.Equal("physics", glass.GetProperty("layer").GetString()); + Assert.False(glass.GetProperty("editable").GetBoolean()); + + Assert.Equal(3, schema.GetProperty("policies").GetArrayLength()); + Assert.Equal("efficient", schema.GetProperty("defaults").GetProperty("policy").GetString()); + Assert.True(schema.GetProperty("snapshots").GetBoolean()); + } + + [Fact] + public async Task Run_round_trips_a_scenario_into_a_result() + { + await using var host = await LabHost.StartAsync(); + const string scenario = """{"changes":{"FloorData[B3].Fare":900,"EconomyData.StepValue":7},"bots":16,"seed":3,"policy":"cheap","policyParams":{"shopSeconds":5}}"""; + + var (status, result) = await host.PostAsync("/run", scenario); + + Assert.Equal(HttpStatusCode.OK, status); + Assert.Equal(16, result.GetProperty("bots").GetInt32()); + Assert.Equal(16, result.GetProperty("finished").GetInt32()); + Assert.True(result.GetProperty("total").GetProperty("median").GetDouble() > 0); + + var echoed = result.GetProperty("scenario"); + Assert.Equal(900, echoed.GetProperty("changes").GetProperty("FloorData[B3].Fare").GetDouble()); + Assert.Equal("cheap", echoed.GetProperty("policy").GetString()); + Assert.Equal(5, echoed.GetProperty("policyParams").GetProperty("shopSeconds").GetDouble()); + + Assert.Equal(new[] { "B1", "B2", "B3", "B4", "B5" }, + result.GetProperty("stages").EnumerateArray().Select(s => s.GetProperty("id").GetString())); + Assert.Equal(360, result.GetProperty("stages")[2].GetProperty("targetSeconds").GetDouble()); + Assert.Equal(121, result.GetProperty("progression").GetProperty("points").GetArrayLength()); + Assert.True(result.GetProperty("purchases").GetProperty("items").GetArrayLength() > 0); + Assert.Equal(2, result.GetProperty("checks").GetArrayLength()); + Assert.Equal("toy-1", result.GetProperty("outcomeVersion").GetString()); + } + + [Fact] + public async Task The_same_request_gives_the_same_result_and_leaves_the_data_files_alone() + { + await using var host = await LabHost.StartAsync(); + var before = host.ReadFiles(); + const string scenario = """{"changes":{"UpgradeData.BaseCost":1.8,"Floors.ValueGrowth":2.4}}"""; + + var (_, first) = await host.PostAsync("/run", scenario); + var (_, second) = await host.PostAsync("/run", scenario); + var (_, baseline) = await host.PostAsync("/run", "{}"); + + Assert.Equal(WithoutTiming(first), WithoutTiming(second)); + Assert.NotEqual( + first.GetProperty("total").GetProperty("median").GetDouble(), + baseline.GetProperty("total").GetProperty("median").GetDouble()); + Assert.Equal(before, host.ReadFiles()); + } + + [Theory] + [InlineData("""{"changes":{"EconomyData.Nope":1}}""", "EconomyData.Nope")] + [InlineData("""{"changes":{"EconomyData.GlassToughness":1.5}}""", "physics")] + [InlineData("""{"policy":"reckless"}""", "reckless")] + [InlineData("""{"bots":0}""", "Bots")] + [InlineData("""{"changes":""", "JSON")] + public async Task A_scenario_that_cannot_run_is_a_400_that_says_why(string body, string expected) + { + await using var host = await LabHost.StartAsync(); + + var (status, error) = await host.PostAsync("/run", body); + + Assert.Equal(HttpStatusCode.BadRequest, status); + Assert.Contains(expected, error.GetProperty("error").GetString()); + } + + [Fact] + public async Task Snapshot_is_saved_listed_and_read_back_with_its_result() + { + await using var host = await LabHost.StartAsync(); + const string body = """{"name":"cheap B3","scenario":{"changes":{"FloorData[B3].Fare":900},"bots":12}}"""; + + var (saveStatus, saved) = await host.PostAsync("/snapshots", body); + var (_, list) = await host.GetAsync("/snapshots"); + var (loadStatus, loaded) = await host.GetAsync("/snapshots/cheap%20B3"); + + Assert.Equal(HttpStatusCode.OK, saveStatus); + var entry = Assert.Single(list.EnumerateArray()); + Assert.Equal("cheap B3", entry.GetProperty("name").GetString()); + Assert.Equal(1, entry.GetProperty("changedKnobs").GetInt32()); + + Assert.Equal(HttpStatusCode.OK, loadStatus); + Assert.Equal(900, loaded.GetProperty("scenario").GetProperty("changes").GetProperty("FloorData[B3].Fare").GetDouble()); + Assert.Equal(12, loaded.GetProperty("scenario").GetProperty("bots").GetInt32()); + Assert.Equal(saved.GetProperty("result").GetRawText(), loaded.GetProperty("result").GetRawText()); + Assert.Equal(saved.GetProperty("baselineHash").GetString(), loaded.GetProperty("baselineHash").GetString()); + + // Running the stored scenario again reproduces the stored picture. + var (_, again) = await host.PostAsync("/run", loaded.GetProperty("scenario").GetRawText()); + Assert.Equal( + loaded.GetProperty("result").GetProperty("stages").GetRawText(), + again.GetProperty("stages").GetRawText()); + } + + [Fact] + public async Task Snapshot_lookups_fail_cleanly() + { + await using var host = await LabHost.StartAsync(); + + Assert.Equal(HttpStatusCode.NotFound, (await host.GetAsync("/snapshots/none")).Status); + Assert.Equal(HttpStatusCode.BadRequest, (await host.GetAsync("/snapshots/..%2Fescape")).Status); + Assert.Equal(HttpStatusCode.BadRequest, (await host.PostAsync("/snapshots", """{"name":"a/b","scenario":{}}""")).Status); + Assert.Equal(HttpStatusCode.BadRequest, (await host.PostAsync("/snapshots", """{"name":"ok","scenario":{"changes":{"Nope":1}}}""")).Status); + Assert.Empty((await host.GetAsync("/snapshots")).Body.EnumerateArray()); + } + + [Fact] + public async Task Without_a_snapshot_store_the_schema_says_so_and_the_routes_are_404() + { + await using var host = await LabHost.StartAsync(snapshots: false); + + var (_, schema) = await host.GetAsync("/schema"); + + Assert.False(schema.GetProperty("snapshots").GetBoolean()); + Assert.Equal(HttpStatusCode.NotFound, (await host.GetAsync("/snapshots")).Status); + Assert.Equal(HttpStatusCode.NotFound, (await host.PostAsync("/snapshots", """{"name":"x","scenario":{}}""")).Status); + } + + [Fact] + public async Task An_editor_save_refreshes_the_labs_baseline() + { + await using var host = await LabHost.StartAsync(); + double StepValue(JsonElement schema) => schema.GetProperty("knobs").EnumerateArray() + .Single(k => k.GetProperty("id").GetString() == "EconomyData.StepValue").GetProperty("baseline").GetDouble(); + + var (_, before) = await host.GetAsync("/schema"); + File.WriteAllText(Path.Combine(host.DataPath, "Economy.yaml"), "StepValue: 9\nIntactBonus: 40\nBottlesPerRun: 3\nGlassToughness: 1\n"); + await host.App.Services.GetRequiredService() + .NotifyAsync(new DataChangedEvent(typeof(Datra.Lab.Sample.Models.EconomyData), DataChangeKind.Saved)); + var (_, after) = await host.GetAsync("/schema"); + + Assert.Equal(5, StepValue(before)); + Assert.Equal(9, StepValue(after)); + Assert.NotEqual(before.GetProperty("baselineHash").GetString(), after.GetProperty("baselineHash").GetString()); + } + + [Fact] + public void AddDatraLab_without_a_raw_data_provider_says_what_is_missing() + { + var services = new ServiceCollection(); + services.AddDatraLab(); + using var provider = services.BuildServiceProvider(); + + var error = Assert.Throws(() => provider.GetRequiredService()); + + Assert.Contains("IRawDataProvider", error.Message); + } +} diff --git a/Datra.WebEditor/Components/DatraLab.razor b/Datra.WebEditor/Components/DatraLab.razor new file mode 100644 index 0000000..302e670 --- /dev/null +++ b/Datra.WebEditor/Components/DatraLab.razor @@ -0,0 +1,45 @@ +@* + Balance lab screen. Mount with `` after registering `AddDatraLab()` + and mapping `MapDatraLab()` (both in Datra.WebEditor.Server). + + The component is only a host: the knob panel and every view are drawn by the framework-free + JavaScript modules under wwwroot/lab, which talk to the lab endpoints. Keeping the drawing out + of Blazor is what lets the same modules render a result baked into a standalone page later. +*@ +@implements IAsyncDisposable +@inject IJSRuntime JS + +
+ +@code { + /// Where MapDatraLab was mounted. + [Parameter] public string BasePath { get; set; } = "/api/datra/lab"; + + /// Language of the screen's own text: "en" (default) or "ko". Knob labels come from the game. + [Parameter] public string? Locale { get; set; } + + private ElementReference _host; + private IJSObjectReference? _module; + + protected override async Task OnAfterRenderAsync(bool firstRender) + { + if (!firstRender) return; + + _module = await JS.InvokeAsync("import", "./_content/Datra.WebEditor/lab/datra-lab.js"); + await _module.InvokeVoidAsync("mount", _host, new { basePath = BasePath, locale = Locale }); + } + + public async ValueTask DisposeAsync() + { + if (_module is null) return; + try + { + await _module.InvokeVoidAsync("unmount", _host); + await _module.DisposeAsync(); + } + catch (JSDisconnectedException) + { + // The circuit is gone and the page with it: nothing left to clean up. + } + } +} diff --git a/Datra.WebEditor/README.md b/Datra.WebEditor/README.md index 64c4944..ddeb8f5 100644 --- a/Datra.WebEditor/README.md +++ b/Datra.WebEditor/README.md @@ -137,6 +137,19 @@ POST /api/datra/reload/{typeName} — discard pending edits and re-read from through the same `DatraEditorHostService` the Blazor UI uses, so external triggers compose cleanly with the in-process editor. +## Balance lab (``) + +A second screen next to the table editor: knobs generated from `[Knob]` attributes, bots that +play the game through a simulator class you write, and views of the outcome. It needs +`AddDatraLab()` and `MapDatraLab()` from Datra.WebEditor.Server. + +```razor + +``` + +The component is a host for framework-free JavaScript modules in `wwwroot/lab/` (the only +JavaScript in this package); they load their own stylesheet. See [docs/LAB.md](../docs/LAB.md). + ## Architecture overview ``` diff --git a/Datra.WebEditor/wwwroot/lab/datra-lab.css b/Datra.WebEditor/wwwroot/lab/datra-lab.css new file mode 100644 index 0000000..b3313ed --- /dev/null +++ b/Datra.WebEditor/wwwroot/lab/datra-lab.css @@ -0,0 +1,175 @@ +/* + * Datra.Lab — balance lab screen. + * + * Everything is scoped under .datra-lab and uses its own --lab-* tokens, so the screen looks the + * same inside a dark editor shell, a plain page, or (later) an exported standalone file. + * Colour roles are fixed: accent = the scenario being looked at, grey = what it is compared + * with, gold = physics, orange + "!" = a warning. + */ +.datra-lab { + --lab-bg: #eef0f2; + --lab-panel: #ffffff; + --lab-panel-2: #f7f8f9; + --lab-line: #e1e4e8; + --lab-line-2: #cfd4da; + --lab-ink: #1d2127; + --lab-ink-2: #4f565f; + --lab-ink-3: #858c95; + --lab-accent: #2f6bd8; + --lab-accent-soft: #e7eefb; + --lab-accent-wash: rgba(47, 107, 216, 0.12); + --lab-base: #7a828c; + --lab-gold-deep: #c7940c; + --lab-gold-soft: #fbf2d6; + --lab-warn: #b85a10; + --lab-warn-soft: #fbeee2; + --lab-good: #2d8a57; + --lab-good-soft: #e3f3ea; + --lab-radius: 12px; + --lab-shadow: 0 1px 2px rgba(20, 24, 30, 0.04), 0 2px 8px rgba(20, 24, 30, 0.04); + --lab-font: "Pretendard Variable", Pretendard, -apple-system, BlinkMacSystemFont, "Apple SD Gothic Neo", "Noto Sans KR", system-ui, sans-serif; + --lab-mono: "JetBrains Mono", ui-monospace, SFMono-Regular, Menlo, monospace; + + background: var(--lab-bg); + color: var(--lab-ink); + font-family: var(--lab-font); + font-size: 14px; + line-height: 1.5; + -webkit-font-smoothing: antialiased; + word-break: keep-all; + min-height: 100%; +} +.datra-lab *, .datra-lab *::before, .datra-lab *::after { box-sizing: border-box; } +.datra-lab button, .datra-lab select, .datra-lab input { font: inherit; color: inherit; } +.datra-lab .num { font-variant-numeric: tabular-nums; } +.datra-lab [hidden] { display: none !important; } + +/* top bar */ +.datra-lab .lab-top { position: sticky; top: 0; z-index: 20; display: flex; align-items: center; gap: 12px; min-height: 56px; padding: 8px 20px; flex-wrap: wrap; background: rgba(238, 240, 242, 0.92); backdrop-filter: blur(10px); border-bottom: 1px solid var(--lab-line); } +.datra-lab .lab-brand { display: flex; align-items: center; gap: 10px; font-weight: 700; letter-spacing: -0.01em; white-space: nowrap; } +.datra-lab .lab-mark { width: 22px; height: 22px; border-radius: 6px; background: var(--lab-ink); display: grid; place-items: center; } +.datra-lab .lab-mark i { width: 8px; height: 8px; border-radius: 50%; background: #e8b21e; display: block; } +.datra-lab .lab-spacer { flex: 1; } +.datra-lab .lab-chip { display: inline-flex; align-items: center; gap: 6px; padding: 4px 10px; border-radius: 999px; background: var(--lab-panel); border: 1px solid var(--lab-line); color: var(--lab-ink-2); font-size: 12.5px; white-space: nowrap; } +.datra-lab .lab-chip b { color: var(--lab-ink); font-weight: 600; } +.datra-lab .lab-chip .dot { width: 7px; height: 7px; border-radius: 50%; background: #3aa76d; } +.datra-lab .lab-chip.busy .dot { background: var(--lab-gold-deep); animation: lab-pulse 1s infinite; } +.datra-lab .lab-chip.bad .dot { background: var(--lab-warn); } +@keyframes lab-pulse { 50% { opacity: 0.3; } } +.datra-lab .lab-btn { display: inline-flex; align-items: center; gap: 6px; padding: 5px 12px; border-radius: 8px; border: 1px solid var(--lab-line-2); background: var(--lab-panel); cursor: pointer; font-weight: 500; white-space: nowrap; font-size: 13px; } +.datra-lab .lab-btn:hover:not(:disabled) { border-color: var(--lab-ink-3); } +.datra-lab .lab-btn:disabled { opacity: 0.45; cursor: default; } +.datra-lab .lab-btn.primary { background: var(--lab-ink); color: #fff; border-color: var(--lab-ink); } +.datra-lab .lab-btn.ghost { border-color: transparent; background: transparent; color: var(--lab-ink-2); } +.datra-lab .lab-btn.small { padding: 3px 9px; font-size: 12.5px; border-radius: 7px; } +.datra-lab .lab-field { display: inline-flex; align-items: center; gap: 6px; font-size: 12.5px; color: var(--lab-ink-2); white-space: nowrap; } +.datra-lab .lab-field select, .datra-lab .lab-field input { border: 1px solid var(--lab-line-2); background: var(--lab-panel); border-radius: 7px; padding: 3px 8px; font-size: 12.5px; color: var(--lab-ink); } +.datra-lab .lab-field input[type=number] { width: 72px; } +.datra-lab .lab-field input[type=text] { width: 150px; } + +/* layout */ +.datra-lab .lab-page { display: grid; grid-template-columns: 300px minmax(0, 1fr); gap: 16px; padding: 16px 20px 40px; max-width: 1560px; margin: 0 auto; } +.datra-lab .lab-rail { display: grid; gap: 12px; align-content: start; } +.datra-lab .lab-main { display: grid; gap: 16px; min-width: 0; align-content: start; } +.datra-lab .lab-grid-2 { display: grid; grid-template-columns: minmax(0, 1.25fr) minmax(0, 1fr); gap: 16px; } +.datra-lab .lab-panel { background: var(--lab-panel); border: 1px solid var(--lab-line); border-radius: var(--lab-radius); box-shadow: var(--lab-shadow); padding: 16px 18px; min-width: 0; } +.datra-lab .lab-panel h2 { margin: 0; font-size: 15px; font-weight: 650; letter-spacing: -0.01em; } +.datra-lab .lab-sub { color: var(--lab-ink-3); font-size: 12.5px; margin-top: 2px; } +.datra-lab .lab-ph { display: flex; align-items: flex-start; justify-content: space-between; gap: 12px; margin-bottom: 10px; } +.datra-lab .lab-lead { font-size: 13.5px; color: var(--lab-ink); margin: 0 0 10px; font-weight: 550; } + +/* bot settings */ +.datra-lab .lab-box { background: var(--lab-panel); border: 1px solid var(--lab-line); border-radius: var(--lab-radius); box-shadow: var(--lab-shadow); padding: 12px 16px; } +.datra-lab .lab-box h3 { margin: 0 0 8px; font-size: 13px; color: var(--lab-ink-2); font-weight: 600; } +.datra-lab .lab-box .rows { display: grid; grid-template-columns: auto minmax(0, 1fr); gap: 6px 10px; align-items: center; font-size: 12.5px; color: var(--lab-ink-2); } +.datra-lab .lab-box .rows select, .datra-lab .lab-box .rows input { border: 1px solid var(--lab-line-2); background: var(--lab-panel); border-radius: 7px; padding: 3px 8px; font-size: 12.5px; color: var(--lab-ink); width: 100%; min-width: 0; } +.datra-lab .lab-box .hint { font-size: 12px; color: var(--lab-ink-3); margin-top: 8px; } + +/* knobs */ +.datra-lab .lab-knobs { background: var(--lab-panel); border: 1px solid var(--lab-line); border-radius: var(--lab-radius); box-shadow: var(--lab-shadow); padding: 6px 0 10px; } +.datra-lab .lab-knobs-head { display: flex; align-items: center; justify-content: space-between; padding: 10px 16px 6px; gap: 8px; } +.datra-lab .lab-knobs-head h3 { margin: 0; font-size: 13px; color: var(--lab-ink-2); font-weight: 600; } +.datra-lab .lab-kgroup { padding: 8px 16px 4px; border-top: 1px solid var(--lab-line); } +.datra-lab .lab-kgroup h4 { margin: 6px 0 4px; font-size: 11.5px; letter-spacing: 0.04em; color: var(--lab-ink-3); font-weight: 600; text-transform: uppercase; } +.datra-lab .lab-knob { padding: 7px 0 6px; } +.datra-lab .lab-knob .row { display: flex; align-items: baseline; justify-content: space-between; gap: 8px; } +.datra-lab .lab-knob label { font-weight: 550; font-size: 13.5px; display: flex; align-items: center; gap: 6px; min-width: 0; } +.datra-lab .lab-knob .val { font-variant-numeric: tabular-nums; font-weight: 600; font-size: 13.5px; white-space: nowrap; } +.datra-lab .lab-knob .val small { color: var(--lab-ink-3); font-weight: 500; margin-left: 3px; } +.datra-lab .lab-knob .src { display: none; font-family: var(--lab-mono); font-size: 10.5px; color: var(--lab-ink-3); margin-top: 2px; overflow-wrap: anywhere; } +.datra-lab .lab-knobs.show-src .lab-knob .src { display: block; } +.datra-lab .lab-knob .changed { width: 6px; height: 6px; border-radius: 50%; background: var(--lab-accent); display: none; flex: none; } +.datra-lab .lab-knob.is-changed .changed { display: inline-block; } +.datra-lab .lab-knob .was { display: none; font-size: 11.5px; color: var(--lab-ink-3); font-variant-numeric: tabular-nums; } +.datra-lab .lab-knob.is-changed .was { display: block; } +.datra-lab .lab-knob .reset { border: 0; background: none; color: var(--lab-ink-3); cursor: pointer; padding: 0 2px; font-size: 12px; visibility: hidden; } +.datra-lab .lab-knob.is-changed .reset { visibility: visible; } +.datra-lab .lab-badge { font-size: 10.5px; font-weight: 600; padding: 1px 6px; border-radius: 4px; background: var(--lab-gold-soft); color: #8a6508; letter-spacing: 0.02em; white-space: nowrap; } +.datra-lab .lab-slider { position: relative; } +.datra-lab .lab-slider .tick { position: absolute; top: 4px; width: 2px; height: 14px; margin-left: -1px; background: var(--lab-ink-3); border-radius: 1px; pointer-events: none; opacity: 0.7; } +.datra-lab input[type=range] { -webkit-appearance: none; appearance: none; width: 100%; height: 22px; background: transparent; margin: 2px 0 0; cursor: pointer; display: block; position: relative; z-index: 1; } +.datra-lab input[type=range]::-webkit-slider-runnable-track { height: 4px; border-radius: 2px; background: linear-gradient(to right, var(--lab-ink) 0 var(--fill, 50%), var(--lab-line-2) var(--fill, 50%) 100%); } +.datra-lab input[type=range]::-webkit-slider-thumb { -webkit-appearance: none; width: 16px; height: 16px; margin-top: -6px; border-radius: 50%; background: #fff; border: 2px solid var(--lab-ink); box-shadow: 0 1px 3px rgba(0, 0, 0, 0.15); position: relative; } +.datra-lab input[type=range]::-moz-range-track { height: 4px; border-radius: 2px; background: var(--lab-line-2); } +.datra-lab input[type=range]::-moz-range-progress { height: 4px; border-radius: 2px; background: var(--lab-ink); } +.datra-lab input[type=range]::-moz-range-thumb { width: 14px; height: 14px; border-radius: 50%; background: #fff; border: 2px solid var(--lab-ink); } +.datra-lab input[type=range]:disabled { cursor: default; opacity: 0.55; } +.datra-lab .lab-knob.physics input[type=range]::-webkit-slider-runnable-track { background: linear-gradient(to right, var(--lab-gold-deep) 0 var(--fill, 50%), var(--lab-line-2) var(--fill, 50%) 100%); } +.datra-lab .lab-knob.physics input[type=range]::-webkit-slider-thumb { border-color: var(--lab-gold-deep); } + +/* hero and tiles */ +.datra-lab .lab-hero { display: grid; grid-template-columns: auto 1fr; gap: 28px; align-items: center; } +.datra-lab .lab-big { font-size: 56px; font-weight: 700; letter-spacing: -0.03em; line-height: 1; font-variant-numeric: tabular-nums; } +.datra-lab .lab-big small { font-size: 22px; font-weight: 600; color: var(--lab-ink-2); margin-left: 4px; letter-spacing: 0; } +.datra-lab .lab-cap { color: var(--lab-ink-2); margin-top: 8px; font-size: 13px; } +.datra-lab .lab-cap b { color: var(--lab-ink); } +.datra-lab .lab-tiles { display: grid; grid-template-columns: repeat(4, minmax(0, 1fr)); gap: 10px; } +.datra-lab .lab-tile { background: var(--lab-panel-2); border: 1px solid var(--lab-line); border-radius: 10px; padding: 10px 12px; min-width: 0; } +.datra-lab .lab-tile .l { color: var(--lab-ink-3); font-size: 12px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; } +.datra-lab .lab-tile .v { font-size: 22px; font-weight: 650; font-variant-numeric: tabular-nums; letter-spacing: -0.02em; margin-top: 2px; white-space: nowrap; } +.datra-lab .lab-tile .v small { font-size: 12.5px; color: var(--lab-ink-3); font-weight: 500; margin-left: 3px; } +.datra-lab .lab-tile .d { font-size: 12px; color: var(--lab-ink-3); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; } +.datra-lab .lab-tile.warn { background: var(--lab-warn-soft); border-color: #f0d6bf; } +.datra-lab .lab-tile.warn .d { color: var(--lab-warn); } +.datra-lab .lab-delta { font-size: 13px; font-weight: 600; font-variant-numeric: tabular-nums; color: var(--lab-ink-2); } + +/* charts */ +.datra-lab .lab-chart { position: relative; width: 100%; } +.datra-lab .lab-chart svg { display: block; width: 100%; overflow: visible; } +.datra-lab .lab-chart text { font-family: var(--lab-font); fill: var(--lab-ink-3); font-size: 11.5px; } +.datra-lab .lab-chart .lbl { fill: var(--lab-ink-2); font-weight: 600; } +.datra-lab .lab-chart .lbl-strong { fill: var(--lab-ink); font-weight: 650; } +.datra-lab .lab-chart .lbl-warn { fill: var(--lab-warn); font-weight: 600; } +.datra-lab .lab-legend { display: flex; flex-wrap: wrap; gap: 14px; font-size: 12.5px; color: var(--lab-ink-2); } +.datra-lab .lab-legend span { display: inline-flex; align-items: center; gap: 6px; white-space: nowrap; } +.datra-lab .lab-legend i { width: 14px; height: 3px; border-radius: 2px; display: inline-block; } +.datra-lab .lab-legend i.sq { width: 10px; height: 10px; border-radius: 3px; } +.datra-lab .lab-legend i.dash { background: repeating-linear-gradient(90deg, var(--lab-ink) 0 4px, transparent 4px 7px); height: 2px; } +.datra-lab .lab-notes { display: grid; gap: 8px; } +.datra-lab .lab-note { display: flex; gap: 10px; align-items: flex-start; padding: 10px 12px; border-radius: 10px; background: var(--lab-panel-2); border: 1px solid var(--lab-line); font-size: 13px; color: var(--lab-ink-2); } +.datra-lab .lab-note .ic { flex: none; width: 18px; height: 18px; border-radius: 50%; display: grid; place-items: center; font-size: 11px; font-weight: 700; background: var(--lab-warn-soft); color: var(--lab-warn); margin-top: 1px; } +.datra-lab .lab-note.info .ic { background: var(--lab-accent-soft); color: var(--lab-accent); } +.datra-lab .lab-note.ok .ic { background: var(--lab-good-soft); color: var(--lab-good); } +.datra-lab .lab-note b { color: var(--lab-ink); } +.datra-lab .lab-table { width: 100%; border-collapse: collapse; font-size: 12.5px; margin-top: 10px; font-variant-numeric: tabular-nums; } +.datra-lab .lab-table th, .datra-lab .lab-table td { text-align: right; padding: 4px 8px; border-bottom: 1px solid var(--lab-line); } +.datra-lab .lab-table th { color: var(--lab-ink-3); font-weight: 600; } +.datra-lab .lab-table th:first-child, .datra-lab .lab-table td:first-child { text-align: left; } +.datra-lab .lab-foot { color: var(--lab-ink-3); font-size: 12px; text-align: center; padding: 6px 0 0; overflow-wrap: anywhere; } +.datra-lab .lab-error { margin: 24px; padding: 14px 16px; border-radius: 10px; background: var(--lab-warn-soft); border: 1px solid #f0d6bf; color: var(--lab-warn); font-size: 13.5px; } +.datra-lab .lab-loading { padding: 40px; color: var(--lab-ink-3); text-align: center; } +.datra-lab.is-stale .lab-chart svg { opacity: 0.6; } + +/* the tooltip lives on so it is never clipped by the host */ +.datra-lab-tip { position: fixed; z-index: 1000; pointer-events: none; background: #1d2127; color: #fff; border-radius: 8px; padding: 7px 10px; font: 12.5px/1.45 -apple-system, BlinkMacSystemFont, "Apple SD Gothic Neo", "Noto Sans KR", system-ui, sans-serif; box-shadow: 0 6px 20px rgba(0, 0, 0, 0.18); opacity: 0; transition: opacity 0.08s; max-width: 280px; } +.datra-lab-tip b { font-weight: 650; } +.datra-lab-tip .m { color: #b9c0c8; } + +@media (max-width: 1180px) { + .datra-lab .lab-tiles { grid-template-columns: repeat(2, minmax(0, 1fr)); } +} +@media (max-width: 900px) { + .datra-lab .lab-page { grid-template-columns: minmax(0, 1fr); padding: 12px 16px 32px; } + .datra-lab .lab-grid-2 { grid-template-columns: minmax(0, 1fr); } + .datra-lab .lab-hero { grid-template-columns: minmax(0, 1fr); gap: 14px; } +} diff --git a/Datra.WebEditor/wwwroot/lab/datra-lab.js b/Datra.WebEditor/wwwroot/lab/datra-lab.js new file mode 100644 index 0000000..a96a538 --- /dev/null +++ b/Datra.WebEditor/wwwroot/lab/datra-lab.js @@ -0,0 +1,390 @@ +// Datra.Lab screen: the entry point imports. +// +// mount(host, { basePath, locale }) draw the lab into `host` +// unmount(host) remove it again +// +// The screen gets everything through a "source": schema(), run(scenario), and the snapshot +// calls. Today that is httpSource (the MapDatraLab endpoints). A standalone export can hand in +// a source that answers from documents embedded in the page — the views below stay as they are. + +import { strings, formatters, escapeHtml } from './lab-text.js'; +import { stageBars, progression, timeline, tip, removeTip } from './lab-views.js'; +import { buildKnobs } from './lab-knobs.js'; + +const mounted = new WeakMap(); + +export function httpSource(basePath) { + const base = (basePath || '/api/datra/lab').replace(/\/$/, ''); + const call = async (path, body) => { + const response = await fetch(base + path, body === undefined ? undefined : { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify(body), + }); + let data = null; + try { data = await response.json(); } catch (e) { /* an empty or non-JSON body */ } + if (!response.ok) throw new Error((data && data.error) || `${response.status} ${response.statusText}`); + return data; + }; + return { + schema: () => call('/schema'), + run: scenario => call('/run', scenario), + snapshots: () => call('/snapshots'), + snapshot: name => call('/snapshots/' + encodeURIComponent(name)), + saveSnapshot: (name, scenario) => call('/snapshots', { name, scenario }), + }; +} + +function ensureStyles() { + const href = new URL('./datra-lab.css', import.meta.url).href; + if ([...document.styleSheets].some(s => s.href === href) || document.querySelector(`link[data-datra-lab]`)) return; + const link = document.createElement('link'); + link.rel = 'stylesheet'; + link.href = href; + link.dataset.datraLab = ''; + document.head.appendChild(link); +} + +export async function mount(host, options) { + options = options || {}; + unmount(host); + ensureStyles(); + + const t = strings(options.locale || document.documentElement.lang); + const fmt = formatters(t); + const source = options.source || httpSource(options.basePath); + const state = { disposed: false }; + mounted.set(host, state); + + host.classList.add('datra-lab'); + host.innerHTML = `
${escapeHtml(t.loading)}
`; + + let schema; + try { + schema = await source.schema(); + } catch (error) { + if (!state.disposed) host.innerHTML = `
${escapeHtml(error.message)}
`; + return; + } + if (state.disposed) return; + + // ---- state ---- + const values = Object.fromEntries(schema.knobs.map(k => [k.id, k.baseline])); + const bot = { + bots: schema.defaults.bots, + seed: schema.defaults.seed, + policy: schema.defaults.policy, + params: Object.fromEntries(schema.policyParams.map(p => [p.id, p.default])), + }; + let result = null; // the scenario on screen + let saved = null; // the saved data under the same bot settings + let savedKey = ''; + let snapshot = null; // the snapshot compared with, if one is picked + let snapshots = []; + + const changes = () => Object.fromEntries(schema.knobs + .filter(k => k.editable && Math.abs(values[k.id] - k.baseline) > 1e-9) + .map(k => [k.id, values[k.id]])); + const botSettings = () => ({ bots: bot.bots, seed: bot.seed, policy: bot.policy, policyParams: { ...bot.params } }); + const scenario = () => ({ changes: changes(), ...botSettings() }); + + // ---- skeleton ---- + host.innerHTML = ` +
+
+
+ + ${escapeHtml(t.compare)} + + + +
+
+ +
+
+
+
–
+
+
+
+
+
+

${escapeHtml(t.stageTitle)}

${escapeHtml(t.stageSub)}
+
+
+
+ +
+
+

${escapeHtml(t.whyTitle)}

${escapeHtml(t.whySub)}
+
+
+
+
+

${escapeHtml(t.progTitle)}

${escapeHtml(t.progSub)}
+
+
+

${escapeHtml(t.timelineTitle)}

${escapeHtml(t.timelineSub)}
+
+
+
+
+
`; + const $ = id => host.querySelector(`[data-id="${id}"]`); + $('title').textContent = schema.title; + + // ---- bot settings ---- + const maxBots = schema.defaults.maxBots || 400; + const botRows = []; + if (schema.policies.length > 1) { + botRows.push(``); + } + botRows.push(``); + botRows.push(``); + for (const p of schema.policyParams) { + botRows.push(` + `); + } + $('bot').innerHTML = botRows.join(''); + $('bot').addEventListener('change', ev => { + const target = ev.target; + if (target.dataset.bot === 'policy') bot.policy = target.value; + else if (target.dataset.bot) { + const n = Math.round(+target.value); + if (Number.isFinite(n)) bot[target.dataset.bot] = target.dataset.bot === 'bots' ? Math.max(1, Math.min(maxBots, n)) : n; + target.value = bot[target.dataset.bot]; + } else if (target.dataset.param) { + const p = schema.policyParams.find(q => q.id === target.dataset.param); + const n = +target.value; + bot.params[p.id] = Number.isFinite(n) ? Math.max(p.min, Math.min(p.max, n)) : p.default; + target.value = bot.params[p.id]; + } + schedule(); + }); + + // ---- knobs ---- + const knobPanel = buildKnobs($('knobs'), schema.knobs, values, { t, fmt, onInput: () => schedule() }); + + // ---- snapshots ---- + const compareSelect = $('compare'); + const paintCompare = () => { + compareSelect.innerHTML = `` + + snapshots.map(s => ``).join(''); + compareSelect.value = snapshot ? snapshot.name : ''; + $('apply').hidden = !snapshot; + }; + const loadSnapshots = async () => { + if (!schema.snapshots) { $('compareBox').hidden = true; $('saveBox').hidden = true; return; } + try { snapshots = await source.snapshots(); } catch (e) { snapshots = []; } + if (!state.disposed) paintCompare(); + }; + compareSelect.addEventListener('change', async () => { + const name = compareSelect.value; + try { snapshot = name ? await source.snapshot(name) : null; } catch (error) { snapshot = null; setStatus('bad', error.message); } + if (state.disposed) return; + paintCompare(); + render(); + }); + $('apply').addEventListener('click', () => { + if (!snapshot) return; + for (const knob of schema.knobs) { + const v = snapshot.scenario.changes ? snapshot.scenario.changes[knob.id] : undefined; + values[knob.id] = v === undefined ? knob.baseline : v; + } + knobPanel.repaint(); + schedule(); + }); + $('save').addEventListener('click', async () => { + const name = $('snapName').value.trim(); + if (!name) { $('snapName').focus(); return; } + try { + await source.saveSnapshot(name, scenario()); + $('snapName').value = ''; + await loadSnapshots(); + setStatus('', t.snapshotSaved(name)); + } catch (error) { + setStatus('bad', error.message); + } + }); + $('tableBtn').addEventListener('click', () => { $('stageTable').hidden = !$('stageTable').hidden; }); + + // ---- running ---- + function setStatus(kind, message) { + const chip = $('status'); + chip.className = 'lab-chip' + (kind ? ' ' + kind : ''); + $('statusText').textContent = message; + } + + // One request at a time, and always a last one for the latest knob position: dragging a + // slider asks for a run on every input event, which would otherwise pile up. + let running = false, again = false; + function schedule() { + if (running) { again = true; return; } + run(); + } + async function run() { + running = true; + again = false; + // A run usually returns within a frame or two. Only say "running" and dim the charts + // when it does not, or the screen flickers on every step of a drag. + const slow = setTimeout(() => { + if (state.disposed) return; + setStatus('busy', t.running); + host.classList.add('is-stale'); + }, 250); + try { + const key = JSON.stringify(botSettings()); + if (!saved || savedKey !== key) { + saved = await source.run({ changes: {}, ...botSettings() }); + savedKey = key; + } + const now = scenario(); + result = Object.keys(now.changes).length === 0 ? saved : await source.run(now); + if (state.disposed) return; + clearTimeout(slow); + host.classList.remove('is-stale'); + setStatus('', t.upToDate); + render(); + } catch (error) { + if (state.disposed) return; + clearTimeout(slow); + setStatus('bad', `${t.failed}: ${error.message}`); + } finally { + clearTimeout(slow); + running = false; + if (again && !state.disposed) run(); + } + } + + // ---- drawing ---- + function comparison() { + const moved = Object.keys(changes()).length; + if (snapshot) return { name: snapshot.name, result: snapshot.result, show: true }; + return { name: t.savedData, result: saved, show: moved > 0 }; + } + + function notes(cmp) { + const list = []; + for (const p of result.problems || []) { + if (p.kind === 'unfinished') list.push({ html: t.unfinished(p.bots) }); + else if (p.kind === 'missingOutcome') list.push({ html: t.missingOutcome(escapeHtml(p.message), p.bots) }); + else list.push({ html: t.botError(escapeHtml(p.message), p.bots) }); + } + if (snapshot && snapshot.baselineHash && snapshot.baselineHash !== schema.baselineHash) + list.push({ kind: 'info', html: escapeHtml(t.baselineMoved) }); + + let targets = 0; + for (const s of result.stages) { + if (s.targetSeconds == null || s.median == null) continue; + targets++; + const d = s.median - s.targetSeconds; + const tolerance = Math.max(30, s.targetSeconds * 0.1); + if (Math.abs(d) <= tolerance) continue; + const why = (result.explains || []).filter(e => e.stage === s.id).map(e => ` ${escapeHtml(e.text)}`).join(''); + const args = [escapeHtml(s.id), fmt.min(Math.abs(d)), fmt.min(s.targetSeconds)]; + list.push({ html: (d > 0 ? t.over(...args) : t.under(...args)) + why }); + } + for (const c of result.checks || []) { + if (c.ok === false) list.push({ html: t.checkFailed(escapeHtml(c.name), fmt.value(c.value, c.unit), escapeHtml(c.target + (c.unit ? fmt.gap + c.unit : ''))) }); + } + if (list.length === 0) list.push({ kind: 'ok', html: escapeHtml(targets > 0 ? t.allOnTarget : t.noTargets) }); + return list; + } + + function render() { + if (!result || state.disposed) return; + const cmp = comparison(); + const total = result.total; + + $('hero').innerHTML = total ? `${fmt.minBare(total.median)}${escapeHtml(t.minutes)}` : '–'; + $('heroCap').innerHTML = total ? t.heroCap(result.bots, result.finished) : escapeHtml(t.noneFinished); + const delta = $('heroDelta'); + if (cmp.show && total && cmp.result && cmp.result.total) { + const d = (total.median - cmp.result.total.median) / 60; + delta.textContent = '· ' + (Math.abs(d) < 0.05 ? t.sameAs(cmp.name) : t.versus(cmp.name, fmt.signed(d) + fmt.gap + t.minutes)); + } else { + delta.textContent = ''; + } + + // tiles: first purchase, the game's checks, and what this run cost to compute + const tiles = []; + const firstCheck = (result.checks || []).find(c => /first purchase|첫 구매/i.test(c.name)); + if (!firstCheck) { + tiles.push({ l: t.firstPurchase, v: result.purchases.firstSeconds == null ? '–' : fmt.minBare(result.purchases.firstSeconds), u: result.purchases.firstSeconds == null ? '' : t.minutes, d: result.purchases.firstSeconds == null ? t.noPurchases : '' }); + } + for (const c of result.checks || []) { + tiles.push({ l: c.name, v: c.value == null ? '–' : fmt.value(c.value), u: c.unit, d: `${t.target} ${c.target}${c.unit ? fmt.gap + c.unit : ''}`, warn: c.ok === false }); + } + tiles.push({ l: t.purchases, v: fmt.value(result.purchases.countMedian), u: '', d: t.perBot }); + if (result.timing) { + tiles.push({ l: t.computed, v: (result.timing.simulatedSeconds / 3600).toFixed(1), u: t.computedUnit, d: t.computedIn(Math.max(1, Math.round(result.timing.elapsedMs))) }); + } + $('tiles').innerHTML = tiles.slice(0, 4).map(x => `
${escapeHtml(x.l)}
${escapeHtml(x.v)}${escapeHtml(x.u || '')}
${escapeHtml(x.d || '')}
`).join(''); + + // time per stage + const legend = [`${escapeHtml(t.legendNow)}`]; + if (cmp.show) legend.push(`${escapeHtml(cmp.name)}`); + legend.push(`${escapeHtml(t.legendTarget)}`); + $('stageLegend').innerHTML = legend.join(''); + $('progLegend').innerHTML = legend.map(s => s.replace('class="sq"', '')).join(''); + stageBars($('stages'), { stages: result.stages, compare: cmp.show && cmp.result ? cmp.result.stages : null, compareName: cmp.name, t, fmt }); + + const cmpStage = id => cmp.show && cmp.result ? cmp.result.stages.find(s => s.id === id) : null; + $('stageTable').innerHTML = `${cmp.show ? `` : ''}` + + result.stages.map(s => `${cmp.show ? `` : ''}`).join('') + '
${escapeHtml(t.stage)}${escapeHtml(t.median)}${escapeHtml(t.range)}${escapeHtml(t.target)}${escapeHtml(cmp.name)}
${escapeHtml(s.label || s.id)}${fmt.min(s.median)}${fmt.minBare(s.p10)}–${fmt.minBare(s.p90)}${s.targetSeconds == null ? '–' : fmt.min(s.targetSeconds)}${fmt.min((cmpStage(s.id) || {}).median)}
'; + + $('notes').innerHTML = notes(cmp).map(n => `
${n.kind === 'ok' ? '✓' : n.kind === 'info' ? 'i' : '!'}
${n.html}
`).join(''); + + // progression and purchases share one time axis + const tMax = Math.max(result.progression.tMax, cmp.show && cmp.result ? cmp.result.progression.tMax : 0); + const series = []; + if (cmp.show && cmp.result) series.push({ name: cmp.name, points: cmp.result.progression.points, role: 'base', band: false }); + series.push({ name: t.legendNow, points: result.progression.points, role: 'now', band: true, endLabel: total ? fmt.min(total.median) : '' }); + progression($('prog'), { stages: result.stages, series, tMax, t, fmt }); + + // A lane per purchase group; when comparing, the other scenario's lane sits right under it. + const lanes = []; + const other = cmp.show && cmp.result ? cmp.result.purchases : null; + const groups = [...new Set([...result.purchases.groups, ...(other ? other.groups : [])])]; + for (const group of groups) { + lanes.push({ label: group || '–', role: 'now', items: result.purchases.items.filter(i => i.group === group) }); + if (other) lanes.push({ label: cmp.name, role: 'base', items: other.items.filter(i => i.group === group) }); + } + timeline($('timeline'), { lanes, stageEnds: result.purchases.stageEnds, tMax, t, fmt }); + + const moved = Object.keys(changes()).length; + $('foot').textContent = [t.footer(schema.context, schema.baselineHash.slice(0, 8), schema.outcomeVersion), moved ? t.changedKnobs(moved) : ''].filter(Boolean).join(' · '); + } + + let resizeTimer; + const onResize = () => { clearTimeout(resizeTimer); resizeTimer = setTimeout(render, 120); }; + window.addEventListener('resize', onResize); + state.dispose = () => { + window.removeEventListener('resize', onResize); + clearTimeout(resizeTimer); + tip(null); + removeTip(); + }; + + setStatus('busy', t.running); + await loadSnapshots(); + schedule(); +} + +export function unmount(host) { + const state = mounted.get(host); + if (!state) return; + state.disposed = true; + if (state.dispose) state.dispose(); + mounted.delete(host); + host.innerHTML = ''; +} diff --git a/Datra.WebEditor/wwwroot/lab/lab-knobs.js b/Datra.WebEditor/wwwroot/lab/lab-knobs.js new file mode 100644 index 0000000..29c63fa --- /dev/null +++ b/Datra.WebEditor/wwwroot/lab/lab-knobs.js @@ -0,0 +1,80 @@ +// The knob panel, built from the schema. It knows nothing about any game: groups, labels, +// units and ranges all come from the [Knob] attributes (or the knobs the game declared in code). + +import { escapeHtml } from './lab-text.js'; + +/** + * @param host element to fill + * @param knobs schema.knobs + * @param values { knobId: value } — mutated as sliders move + * @param o { t, fmt, onInput(knob, dragging) } + * @returns { repaint() } to call after values were changed from outside + */ +export function buildKnobs(host, knobs, values, o) { + const { t, fmt } = o; + host.innerHTML = ''; + const box = document.createElement('div'); + box.className = 'lab-knobs'; + box.innerHTML = `

${escapeHtml(t.knobs)}

+ +
`; + host.appendChild(box); + + const inputs = []; + const groups = [...new Set(knobs.map(k => k.group || ''))]; + for (const group of groups) { + const section = document.createElement('div'); + section.className = 'lab-kgroup'; + if (group) section.innerHTML = `

${escapeHtml(group)}

`; + box.appendChild(section); + + for (const knob of knobs.filter(k => (k.group || '') === group)) { + const physics = knob.layer === 'physics'; + const row = document.createElement('div'); + row.className = 'lab-knob' + (physics ? ' physics' : ''); + row.title = [knob.hint, physics ? t.physicsHint : ''].filter(Boolean).join('\n'); + const source = knob.source + ? `${knob.source.file} · ${knob.source.dataType}${knob.source.row ? `[${knob.source.row}]` : ''}.${knob.source.property}` + : knob.id; + const basePct = (knob.baseline - knob.min) / (knob.max - knob.min) * 100; + row.innerHTML = ` +
+ + ${escapeHtml(knob.unit)} +
+
+ + ${basePct >= 0 && basePct <= 100 ? `` : ''} +
+
${escapeHtml(t.was)} ${fmt.knob(knob, knob.baseline)}
+
${escapeHtml(source)}
`; + section.appendChild(row); + + const input = row.querySelector('input'), shown = row.querySelector('[data-v]'); + const paint = () => { + const v = values[knob.id]; + input.value = v; + shown.textContent = fmt.knob(knob, v); + input.style.setProperty('--fill', Math.max(0, Math.min(100, (v - knob.min) / (knob.max - knob.min) * 100)) + '%'); + row.classList.toggle('is-changed', Math.abs(v - knob.baseline) > 1e-9); + }; + input.addEventListener('input', () => { values[knob.id] = +input.value; paint(); o.onInput(knob, true); }); + input.addEventListener('change', () => o.onInput(knob, false)); + row.querySelector('.reset').addEventListener('click', () => { values[knob.id] = knob.baseline; paint(); o.onInput(knob, false); }); + paint(); + inputs.push(paint); + } + } + + box.querySelector('[data-act="src"]').addEventListener('click', ev => { + const on = box.classList.toggle('show-src'); + ev.target.textContent = on ? t.hideFields : t.showFields; + }); + box.querySelector('[data-act="reset"]').addEventListener('click', () => { + for (const knob of knobs) values[knob.id] = knob.baseline; + inputs.forEach(paint => paint()); + o.onInput(null, false); + }); + + return { repaint() { inputs.forEach(paint => paint()); } }; +} diff --git a/Datra.WebEditor/wwwroot/lab/lab-text.js b/Datra.WebEditor/wwwroot/lab/lab-text.js new file mode 100644 index 0000000..f170aec --- /dev/null +++ b/Datra.WebEditor/wwwroot/lab/lab-text.js @@ -0,0 +1,189 @@ +// Text of the lab screen itself, and number formatting. Knob labels, stage names and +// explanations come from the game and are shown as they are. + +const STRINGS = { + en: { + loading: 'Loading the lab…', + knobs: 'Knobs', + showFields: 'Show data fields', + hideFields: 'Hide data fields', + physics: 'physics', + physicsHint: 'Reaches the physics layer. Read-only until stored outcomes can be recomputed.', + resetKnob: 'Back to the saved value', + resetAll: 'Reset', + was: 'saved', + mixed: 'rows differ', + bots: 'Bots', + botSettings: 'Bots', + policy: 'Policy', + seed: 'Seed', + botHint: 'Both sides of a comparison play with the same seeds, so only the knobs differ.', + compare: 'Compare with', + savedData: 'Saved data', + applyKnobs: 'Use its knobs', + saveSnapshot: 'Save snapshot', + snapshotName: 'Snapshot name', + snapshotSaved: name => `Saved snapshot "${name}".`, + upToDate: 'Up to date', + running: 'Running bots…', + failed: 'Run failed', + heroCap: (bots, finished) => finished === bots + ? `to play through, median of ${bots} bots` + : `to play through, median of the ${finished} of ${bots} bots that finished`, + noneFinished: 'No bot finished', + sameAs: name => `same as ${name}`, + versus: (name, delta) => `${delta} vs ${name}`, + firstPurchase: 'First purchase', + purchases: 'Purchases', + perBot: 'per bot, median', + noPurchases: 'nothing bought', + target: 'target', + computed: 'This run', + computedUnit: 'h played', + computedIn: ms => `by the bots in ${ms} ms`, + stageTitle: 'Time per stage', + stageSub: 'Bar: median across bots. Thin line: the middle 80%. Dashed: target.', + whyTitle: 'Against the targets', + whySub: 'Written from the result. Reasons in italics come from the game’s simulator.', + progTitle: 'Progression: where the bots are', + progSub: 'Line: median. Band: the middle 80%. Dashed: the target pace.', + timelineTitle: 'Purchase timeline', + timelineSub: 'One representative bot (the one closest to the median). Dot size: price.', + legendNow: 'This scenario', + legendTarget: 'Target', + end: 'End', + table: 'Table', + stage: 'Stage', + median: 'Median', + range: 'Middle 80%', + over: (id, d, t) => `${id} runs ${d} over its target of ${t}.`, + under: (id, d, t) => `${id} runs ${d} under its target of ${t}.`, + allOnTarget: 'Every stage is within reach of its target.', + noTargets: 'No stage has a target yet.', + checkFailed: (name, value, target) => `${name} is ${value}. Target: ${target}.`, + unfinished: n => `${n} bots were still playing at the time cap. Their last stage has no length.`, + missingOutcome: (key, n) => `No stored physics outcomes for ${key}. ${n} bots stopped there.`, + botError: (message, n) => `${n} bots stopped with an error: ${message}`, + changedKnobs: n => n === 1 ? '1 knob moved' : `${n} knobs moved`, + baselineMoved: 'The saved data has changed since this snapshot was taken.', + minutes: 'min', + seconds: 's', + unitGap: ' ', + tipStage: (now, target) => `median ${now}${target ? ` · target ${target}` : ''}`, + tipRange: (lo, hi) => `80% of bots: ${lo}–${hi}`, + tipCost: 'price', + tipDone: 'finished', + tipStageFill: (id, pct) => `${id} · ${pct}% of the way`, + footer: (context, hash, outcomes) => `${context} · baseline ${hash}${outcomes ? ` · physics outcomes ${outcomes}` : ''}`, + }, + ko: { + loading: '실험실을 불러오는 중…', + knobs: '손잡이', + showFields: '표 필드 보기', + hideFields: '표 필드 숨기기', + physics: '물리', + physicsHint: '물리 층에 닿는 값입니다. 저장된 물리 결과를 다시 계산할 수 있을 때까지 읽기 전용입니다.', + resetKnob: '저장된 값으로', + resetAll: '되돌리기', + was: '저장값', + mixed: '행마다 다름', + bots: '봇', + botSettings: '봇', + policy: '정책', + seed: '시드', + botHint: '비교하는 양쪽이 같은 시드로 돌기 때문에 차이는 손잡이에서만 옵니다.', + compare: '비교 대상', + savedData: '저장된 데이터', + applyKnobs: '이 손잡이 값 쓰기', + saveSnapshot: '스냅샷 저장', + snapshotName: '스냅샷 이름', + snapshotSaved: name => `스냅샷 "${name}" 을 저장했습니다.`, + upToDate: '최신', + running: '봇을 돌리는 중…', + failed: '실행 실패', + heroCap: (bots, finished) => finished === bots + ? `완주 시간, 봇 ${bots}명 중앙값` + : `완주 시간, 봇 ${bots}명 중 끝까지 간 ${finished}명의 중앙값`, + noneFinished: '끝까지 간 봇이 없음', + sameAs: name => `${name} 와 같음`, + versus: (name, delta) => `${name} 대비 ${delta}`, + firstPurchase: '첫 구매', + purchases: '구매 수', + perBot: '봇 한 명, 중앙값', + noPurchases: '구매 없음', + target: '목표', + computed: '이번 계산', + computedUnit: '시간 분량', + computedIn: ms => `봇 플레이를 ${ms} ms 에`, + stageTitle: '단계마다 걸리는 시간', + stageSub: '막대는 봇 중앙값, 가는 선은 80% 범위, 점선은 목표.', + whyTitle: '목표와 견주면', + whySub: '결과에서 뽑은 문장. 기울인 이유는 게임의 시뮬레이터가 적은 것.', + progTitle: '진행: 언제 어느 단계에 있나', + progSub: '선은 봇 중앙값, 띠는 80% 범위, 점선은 목표 속도.', + timelineTitle: '구매 타임라인', + timelineSub: '대표 봇 한 명(완주 시간이 중앙값에 가장 가까운 봇). 점 크기는 가격.', + legendNow: '지금 시나리오', + legendTarget: '목표', + end: '끝', + table: '표', + stage: '단계', + median: '중앙값', + range: '80% 범위', + over: (id, d, t) => `${id} 가 목표 ${t}보다 ${d} 길다.`, + under: (id, d, t) => `${id} 는 목표 ${t}보다 ${d} 짧다.`, + allOnTarget: '모든 단계가 목표 근처다.', + noTargets: '목표가 있는 단계가 없다.', + checkFailed: (name, value, target) => `${name} ${value}. 목표는 ${target}.`, + unfinished: n => `봇 ${n}명이 시간 상한까지 끝내지 못했다. 마지막 단계는 길이가 없다.`, + missingOutcome: (key, n) => `${key} 의 저장된 물리 결과가 없다. 봇 ${n}명이 거기서 멈췄다.`, + botError: (message, n) => `봇 ${n}명이 오류로 멈췄다: ${message}`, + changedKnobs: n => `손잡이 ${n}개 바꿈`, + baselineMoved: '이 스냅샷을 찍은 뒤로 저장된 데이터가 바뀌었다.', + minutes: '분', + seconds: '초', + unitGap: '', + tipStage: (now, target) => `중앙값 ${now}${target ? ` · 목표 ${target}` : ''}`, + tipRange: (lo, hi) => `봇 80%가 ${lo}–${hi}`, + tipCost: '가격', + tipDone: '완주', + tipStageFill: (id, pct) => `${id} · ${pct}%`, + footer: (context, hash, outcomes) => `${context} · 기준 ${hash}${outcomes ? ` · 물리 결과 ${outcomes}` : ''}`, + }, +}; + +export function strings(locale) { + const key = (locale || 'en').toLowerCase().slice(0, 2); + return STRINGS[key] || STRINGS.en; +} + +export function escapeHtml(value) { + return String(value ?? '').replace(/[&<>"']/g, c => ({ '&': '&', '<': '<', '>': '>', '"': '"', "'": ''' }[c])); +} + +/** Decimals a knob's step calls for: step 0.05 shows two, step 50 shows none. */ +export function decimalsFor(step) { + if (!(step > 0) || step >= 1) return 0; + return Math.min(4, Math.ceil(-Math.log10(step) - 1e-9)); +} + +export function formatters(t) { + const number = (v, d = 0) => Number(v).toLocaleString('en-US', { minimumFractionDigits: d, maximumFractionDigits: d }); + // English sets a number off from its unit ("4.0 min"); Korean does not ("4.0분"). + const gap = t.unitGap; + return { + number, + gap, + knob: (knob, v) => number(v, decimalsFor(knob.step)), + /** Seconds shown as minutes. */ + min: (seconds, d = 1) => (seconds == null || !isFinite(seconds) ? '–' : (seconds / 60).toFixed(d)) + gap + t.minutes, + minBare: (seconds, d = 1) => (seconds == null || !isFinite(seconds) ? '–' : (seconds / 60).toFixed(d)), + sec: seconds => (seconds == null || !isFinite(seconds) ? '–' : Math.round(seconds)) + gap + t.seconds, + signed: (v, d = 1) => (v > 0 ? '+' : v < 0 ? '−' : '±') + Math.abs(v).toFixed(d), + value: (v, unit) => { + if (v == null || !isFinite(v)) return '–'; + const d = Math.abs(v) >= 100 || Number.isInteger(v) ? 0 : 1; + return number(v, d) + (unit ? gap + unit : ''); + }, + }; +} diff --git a/Datra.WebEditor/wwwroot/lab/lab-views.js b/Datra.WebEditor/wwwroot/lab/lab-views.js new file mode 100644 index 0000000..2e89249 --- /dev/null +++ b/Datra.WebEditor/wwwroot/lab/lab-views.js @@ -0,0 +1,297 @@ +// The lab's views. Framework-free: every view is a function (container, data) that draws +// SVG into the container. A view sees only the result document — stages, progression points, +// purchases — never the game, so the same code draws a live run, a stored snapshot, or a +// result baked into a standalone page. + +const NS = 'http://www.w3.org/2000/svg'; + +/** Left gutter shared by the progression and the timeline, so their time axes line up. */ +const GUTTER = 96; + +export function el(tag, attrs, parent) { + const e = document.createElementNS(NS, tag); + for (const k in attrs || {}) if (attrs[k] !== undefined && attrs[k] !== null) e.setAttribute(k, attrs[k]); + if (parent) parent.appendChild(e); + return e; +} + +function text(parent, x, y, s, attrs) { + const t = el('text', Object.assign({ x, y }, attrs || {}), parent); + t.textContent = s; + return t; +} + +function lin(d0, d1, r0, r1) { + const f = v => r0 + (v - d0) / ((d1 - d0) || 1) * (r1 - r0); + f.inv = px => d0 + (px - r0) / ((r1 - r0) || 1) * (d1 - d0); + return f; +} + +function ticks(min, max, n) { + const span = max - min || 1; + const raw = span / (n || 5); + const mag = Math.pow(10, Math.floor(Math.log10(raw))); + const step = [1, 2, 2.5, 5, 10].map(s => s * mag).find(s => s >= raw) || raw; + const out = []; + for (let v = Math.ceil(min / step) * step; v <= max + step * 1e-9; v += step) out.push(+v.toFixed(10)); + return out; +} + +/** Colours are read from the host's --lab-* tokens so a theme override reaches the SVG too. */ +function palette(container) { + const style = getComputedStyle(container.closest('.datra-lab') || container); + const get = name => style.getPropertyValue(name).trim(); + return { + ink: get('--lab-ink') || '#1d2127', + ink3: get('--lab-ink-3') || '#858c95', + line: get('--lab-line') || '#e1e4e8', + line2: get('--lab-line-2') || '#cfd4da', + panel: get('--lab-panel') || '#ffffff', + accent: get('--lab-accent') || '#2f6bd8', + wash: get('--lab-accent-wash') || 'rgba(47,107,216,0.12)', + base: get('--lab-base') || '#7a828c', + }; +} + +let tipEl; +export function tip(html, ev) { + if (!tipEl) { + tipEl = document.createElement('div'); + tipEl.className = 'datra-lab-tip'; + document.body.appendChild(tipEl); + } + if (html == null) { tipEl.style.opacity = 0; return; } + tipEl.innerHTML = html; + tipEl.style.opacity = 1; + const r = tipEl.getBoundingClientRect(); + let x = ev.clientX + 14, y = ev.clientY + 14; + if (x + r.width > innerWidth - 8) x = ev.clientX - r.width - 14; + if (y + r.height > innerHeight - 8) y = ev.clientY - r.height - 14; + tipEl.style.left = x + 'px'; + tipEl.style.top = y + 'px'; +} + +export function removeTip() { + if (tipEl) { tipEl.remove(); tipEl = null; } +} + +function mount(container, h) { + container.innerHTML = ''; + const w = Math.max(240, container.clientWidth); + const svg = el('svg', { viewBox: `0 0 ${w} ${h}`, width: w, height: h, role: 'img' }, container); + return { svg, w, h }; +} + +/** A column with a 4px rounded data end and a square foot on the baseline. */ +function roundTopRect(parent, x, y, w, h, r, attrs) { + if (h <= 0) return null; + r = Math.min(r, w / 2, h); + const d = `M${x},${y + h}V${y + r}Q${x},${y} ${x + r},${y}H${x + w - r}Q${x + w},${y} ${x + w},${y + r}V${y + h}Z`; + return el('path', Object.assign({ d }, attrs), parent); +} + +// ---------- time per stage: columns, an 80% whisker, a target tick; optional comparison pairs ---------- +/** + * @param o.stages [{ id, label, median, p10, p90, targetSeconds }] (seconds) + * @param o.compare the same, for the scenario compared with (matched by id), or null + * @param o.t, o.fmt strings and formatters + */ +export function stageBars(container, o) { + const { svg, w, h } = mount(container, o.height || 240); + const c = palette(container); + const m = { l: 36, r: 8, t: 28, b: 36 }; + const stages = o.stages; + const compare = o.compare ? stages.map(s => o.compare.find(b => b.id === s.id) || null) : null; + const minutes = v => v == null ? null : v / 60; + + const tops = []; + stages.forEach((s, i) => { + tops.push(minutes(s.p90 ?? s.median), minutes(s.targetSeconds)); + if (compare && compare[i]) tops.push(minutes(compare[i].p90 ?? compare[i].median)); + }); + const ymax = Math.max(1, ...tops.filter(v => v != null)) * 1.14; + const y = lin(0, ymax, h - m.b, m.t); + + for (const tk of ticks(0, ymax, 4)) { + el('line', { x1: m.l, x2: w - m.r, y1: y(tk), y2: y(tk), stroke: c.line, 'shape-rendering': 'crispEdges' }, svg); + text(svg, m.l - 8, y(tk) + 4, tk, { 'text-anchor': 'end' }); + } + text(svg, m.l - 8, m.t - 14, o.t.minutes, { 'text-anchor': 'end' }); + + const band = (w - m.l - m.r) / Math.max(1, stages.length); + stages.forEach((s, i) => { + const cx = m.l + band * (i + 0.5); + const group = el('g', {}, svg); + // A hit area wider than the marks, so hovering anywhere in the column works. + el('rect', { x: cx - band / 2, y: m.t - 20, width: band, height: h - m.t + 20, fill: 'transparent' }, group); + const bw = Math.min(compare ? 22 : 30, band * 0.3); + const base = compare ? compare[i] : null; + + const drawBar = (d, x, color, label) => { + if (d.median == null) return; + const top = y(minutes(d.median)); + roundTopRect(group, x - bw / 2, top, bw, y(0) - top, 4, { fill: color }); + if (d.p10 != null && d.p90 != null) { + const lo = y(minutes(d.p10)), hi = y(minutes(d.p90)); + for (const [x1, x2, y1, y2] of [[x, x, lo, hi], [x - 4, x + 4, hi, hi], [x - 4, x + 4, lo, lo]]) + el('line', { x1, x2, y1, y2, stroke: c.ink, 'stroke-width': 1.2, opacity: 0.45 }, group); + } + if (label) text(group, x, Math.min(top, d.p90 != null ? y(minutes(d.p90)) : 1e9) - 7, label, { 'text-anchor': 'middle', class: 'lbl num' }); + }; + + if (base) { + // 2px of surface between the pair so the two fills never touch. + drawBar(base, cx - bw / 2 - 1, c.base); + drawBar(s, cx + bw / 2 + 1, c.accent); + if (s.median != null && base.median != null) { + const dv = (s.median - base.median) / 60; + text(group, cx, m.t - 8, o.fmt.signed(dv), { 'text-anchor': 'middle', class: Math.abs(dv) < 0.05 ? '' : 'lbl-strong num' }); + } + } else { + drawBar(s, cx, c.accent, s.median == null ? '–' : o.fmt.minBare(s.median)); + } + + if (s.targetSeconds != null) { + const tw = base ? bw * 2 + 16 : bw + 16; + const ty = y(minutes(s.targetSeconds)); + el('line', { x1: cx - tw / 2, x2: cx + tw / 2, y1: ty, y2: ty, stroke: c.ink, 'stroke-width': 2, 'stroke-dasharray': '3 2' }, group); + } + + text(svg, cx, h - m.b + 16, s.id, { 'text-anchor': 'middle', class: 'lbl' }); + if (s.targetSeconds != null && s.median != null) { + const over = (s.median - s.targetSeconds) / 60; + const off = Math.abs(over) > Math.max(0.5, s.targetSeconds / 60 * 0.1); + text(svg, cx, h - m.b + 30, off ? `${o.t.target} ${o.fmt.signed(over)}` : `${o.t.target} ${o.fmt.minBare(s.targetSeconds, 0)}`, + { 'text-anchor': 'middle', class: off ? 'lbl-warn' : '' }); + } + + group.addEventListener('mousemove', ev => { + const rows = [`${esc(s.label || s.id)}`, o.t.tipStage(o.fmt.min(s.median), s.targetSeconds != null ? o.fmt.min(s.targetSeconds) : '')]; + if (s.p10 != null) rows.push(`${o.t.tipRange(o.fmt.minBare(s.p10), o.fmt.min(s.p90))}`); + if (base && base.median != null) rows.push(`${esc(o.compareName)}: ${o.fmt.min(base.median)}`); + tip(rows.join('
'), ev); + }); + group.addEventListener('mouseleave', () => tip(null)); + }); +} + +// ---------- progression: which stage the bots are in, and how far through it, over time ---------- +/** + * @param o.stages [{ id, targetSeconds }] top to bottom + * @param o.series [{ points: [{ t, p10, median, p90 }], role: 'now' | 'base', band, endLabel, name }] + * @param o.tMax seconds + */ +export function progression(container, o) { + const { svg, w, h } = mount(container, o.height || 290); + const c = palette(container); + const m = { l: GUTTER, r: 56, t: 12, b: 30 }; + const n = o.stages.length; + const tmax = Math.max(1, o.tMax / 60); + const x = lin(0, tmax, m.l, w - m.r), y = lin(0, n, m.t, h - m.b); + + for (let k = 0; k <= n; k++) + el('line', { x1: m.l, x2: w - m.r, y1: y(k), y2: y(k), stroke: c.line, 'shape-rendering': 'crispEdges' }, svg); + o.stages.forEach((s, k) => text(svg, m.l - 10, y(k + 0.5) + 4, s.id, { 'text-anchor': 'end', class: 'lbl' })); + text(svg, m.l - 10, y(n) + 4, o.t.end, { 'text-anchor': 'end', class: 'lbl' }); + for (const tk of ticks(0, tmax, 8)) { + text(svg, x(tk), h - m.b + 18, tk + (tk === 0 ? '' : o.fmt.gap + o.t.minutes), { 'text-anchor': 'middle' }); + el('line', { x1: x(tk), x2: x(tk), y1: h - m.b, y2: h - m.b + 4, stroke: c.line2 }, svg); + } + + // Target pace: each stage done in exactly its target time. + if (o.stages.every(s => s.targetSeconds != null)) { + let cum = 0; + const pts = [[x(0), y(0)]]; + o.stages.forEach((s, i) => { cum += s.targetSeconds / 60; if (cum <= tmax * 1.001) pts.push([x(cum), y(i + 1)]); }); + el('polyline', { points: pts.map(p => p.join(',')).join(' '), fill: 'none', stroke: c.ink3, 'stroke-width': 1.5, 'stroke-dasharray': '4 4' }, svg); + } + + for (const s of o.series) { + const G = s.points.filter(p => p.t / 60 <= tmax * 1.0001); + if (G.length === 0) continue; + const color = s.role === 'base' ? c.base : c.accent; + if (s.band) { + const top = G.map(p => `${x(p.t / 60)},${y(p.p10)}`).join(' '); + const bottom = G.slice().reverse().map(p => `${x(p.t / 60)},${y(p.p90)}`).join(' '); + el('polygon', { points: top + ' ' + bottom, fill: c.wash }, svg); + } + el('polyline', { points: G.map(p => `${x(p.t / 60)},${y(p.median)}`).join(' '), fill: 'none', stroke: color, 'stroke-width': 2, 'stroke-linejoin': 'round' }, svg); + const last = G.find(p => p.median >= n - 1e-6) || G[G.length - 1]; + el('circle', { cx: x(last.t / 60), cy: y(last.median), r: 4.5, fill: color, stroke: c.panel, 'stroke-width': 2 }, svg); + if (s.endLabel) text(svg, x(last.t / 60) + 8, y(last.median) - 8, s.endLabel, { 'text-anchor': 'start', class: 'lbl-strong num' }); + } + + const cross = el('line', { y1: m.t, y2: h - m.b, stroke: c.ink, 'stroke-width': 1, opacity: 0 }, svg); + const hit = el('rect', { x: m.l, y: m.t, width: w - m.l - m.r, height: h - m.t - m.b, fill: 'transparent' }, svg); + hit.addEventListener('mousemove', ev => { + const r = svg.getBoundingClientRect(); + const px = (ev.clientX - r.left) * (w / r.width); + const tm = x.inv(px); + cross.setAttribute('x1', px); cross.setAttribute('x2', px); cross.setAttribute('opacity', 0.35); + const rows = o.series.map(s => { + let p = s.points[0]; + for (const q of s.points) { if (q.t / 60 > tm) break; p = q; } + if (!p) return ''; + const k = Math.min(n - 1, Math.floor(p.median)); + const where = p.median >= n - 1e-6 ? o.t.tipDone : o.t.tipStageFill(esc(o.stages[k].id), Math.round((p.median - k) * 100)); + return `${esc(s.name)}: ${where}`; + }); + tip(`${tm.toFixed(1)}${o.fmt.gap}${o.t.minutes}
${rows.join('
')}`, ev); + }); + hit.addEventListener('mouseleave', () => { cross.setAttribute('opacity', 0); tip(null); }); +} + +// ---------- purchase timeline: one dot per purchase, a lane per group ---------- +/** + * @param o.lanes [{ label, role: 'now' | 'base', items: [{ t, label, cost, stage }] }] (t in seconds) + * @param o.stageEnds [{ id, t }] of the representative bot + */ +export function timeline(container, o) { + const laneH = 26, pad = 8; + const { svg, w, h } = mount(container, pad * 2 + Math.max(1, o.lanes.length) * laneH + 22); + const c = palette(container); + const m = { l: GUTTER, r: 56, t: pad, b: 22 }; + const tmax = Math.max(1, o.tMax / 60); + const x = lin(0, tmax, m.l, w - m.r); + + // The label names the stage the bot enters, so the last end (the finish) gets none. + (o.stageEnds || []).forEach((end, i) => { + if (i >= o.stageEnds.length - 1 || end.t / 60 > tmax) return; + const px = x(end.t / 60); + el('line', { x1: px, x2: px, y1: m.t, y2: h - m.b, stroke: c.line2, 'stroke-dasharray': '2 3' }, svg); + const next = o.stageEnds[i + 1]; + if (next) text(svg, px + 4, h - m.b + 14, '↓ ' + next.id, { style: 'font-size:10.5px' }); + }); + + // Lane labels can be longer than the gutter: measure, then trim with an ellipsis. + const fit = (node, max) => { + let s = node.textContent; + try { + while (s.length > 1 && node.getComputedTextLength() > max) { s = s.slice(0, -1); node.textContent = s + '…'; } + } catch (e) { /* not laid out (hidden tab): leave the text as it is */ } + }; + + o.lanes.forEach((lane, li) => { + const cy = m.t + laneH * (li + 0.5); + el('line', { x1: m.l, x2: w - m.r, y1: cy, y2: cy, stroke: c.line }, svg); + const color = lane.role === 'base' ? c.base : c.accent; + const label = text(svg, m.l - 10, cy + 4, lane.label, { 'text-anchor': 'end', class: lane.role === 'base' ? '' : 'lbl' }); + const title = el('title', {}, label); title.textContent = lane.label; + fit(label, m.l - 14); + for (const it of lane.items) { + if (it.t / 60 > tmax) continue; + const r = Math.max(4, Math.min(7, 2.4 + Math.log10(it.cost + 1) * 0.9)); + const dot = el('circle', { cx: x(it.t / 60), cy, r, fill: color, stroke: c.panel, 'stroke-width': 2 }, svg); + const hit = el('circle', { cx: x(it.t / 60), cy, r: r + 5, fill: 'transparent' }, svg); + hit.addEventListener('mousemove', ev => { + dot.setAttribute('r', r + 1.5); + tip(`${esc(it.label)}
${(it.t / 60).toFixed(1)}${o.fmt.gap}${o.t.minutes} · ${esc(it.stage)}
${o.t.tipCost} ${o.fmt.number(it.cost)}`, ev); + }); + hit.addEventListener('mouseleave', () => { dot.setAttribute('r', r); tip(null); }); + } + }); +} + +function esc(value) { + return String(value ?? '').replace(/[&<>"']/g, ch => ({ '&': '&', '<': '<', '>': '>', '"': '"', "'": ''' }[ch])); +} From bd98fc6cdb9301ca99f261e4f1fd982ca8a747be Mon Sep 17 00:00:00 2001 From: penspanic Date: Wed, 30 Sep 2026 19:41:58 +0900 Subject: [PATCH 3/3] docs: balance lab guide docs/LAB.md: what Datra provides and what a game writes, the consumer code, knob semantics, the simulator contract, endpoints, and what P0 leaves out. Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 3 + README.ko.md | 1 + README.md | 1 + docs/LAB.md | 311 +++++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 316 insertions(+) create mode 100644 docs/LAB.md diff --git a/CLAUDE.md b/CLAUDE.md index 48cb46e..8794607 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -31,6 +31,9 @@ Datra/ │ ├── Models/ # DataModelInfo, PropertyInfo 등 │ └── DataContextSourceGenerator.cs # 메인 진입점 (ISourceGenerator) │ +├── Datra.Lab/ # 밸런스 실험실 코어 (UI 없음): 손잡이 스키마, 갈래 컨텍스트, 시뮬레이터 계약, 봇 실행기 +├── Datra.Lab.Sample/ # 실험실용 장난감 게임 데이터 + 시뮬레이터 (웹 샘플·테스트 공용) +├── Datra.Lab.Tests/ # 실험실 코어 테스트 ├── Datra.Analyzers/ # Roslyn Analyzer ├── Datra.SampleData/ # 테스트용 샘플 데이터 모델 ├── Datra.SampleData2/ # 멀티 컨텍스트 테스트용 diff --git a/README.ko.md b/README.ko.md index 20b7df0..6f80808 100644 --- a/README.ko.md +++ b/README.ko.md @@ -120,6 +120,7 @@ Datra/ - **[기능 가이드](docs/FEATURES.md)** - 상세 기능 문서 - **[Unity 가이드](docs/UNITY.md)** - Unity 통합 가이드 +- **[밸런스 실험실](docs/LAB.md)** - 수치를 결과로 보고 맞추기: 손잡이, 봇, 게임이 한 번 쓰는 시뮬레이터 - **[개발자 가이드](CLAUDE.md)** - 내부 개발 가이드 ## 라이선스 diff --git a/README.md b/README.md index e8ee34c..f739789 100644 --- a/README.md +++ b/README.md @@ -147,6 +147,7 @@ Datra/ - **[Features Guide](docs/FEATURES.md)** - Detailed feature documentation - **[Unity Guide](docs/UNITY.md)** - Unity integration guide +- **[Balance Lab](docs/LAB.md)** - Tune numbers by their outcome: knobs, bots, a simulator you write once - **[Developer Guide](CLAUDE.md)** - Internal development guide ## License diff --git a/docs/LAB.md b/docs/LAB.md new file mode 100644 index 0000000..45c4f12 --- /dev/null +++ b/docs/LAB.md @@ -0,0 +1,311 @@ +# Balance Lab + +The lab answers "what happens if I change this number" without anyone reading a table. You +move a knob (a named value with a unit and a range), a batch of bots plays the game from start +to finish with the new value, and the time per stage, the progression curve and the purchase +order are redrawn. Nothing is written to your data files while you do this. + +This is the first slice (P0): economy knobs, three views, snapshots. See +[What is not here yet](#what-is-not-here-yet). + +## Table of Contents + +- [Who provides what](#who-provides-what) +- [Adopting it](#adopting-it) +- [Knobs](#knobs) +- [The simulator](#the-simulator) +- [Stored physics outcomes](#stored-physics-outcomes) +- [Scenarios, results, snapshots](#scenarios-results-snapshots) +- [HTTP endpoints](#http-endpoints) +- [Without a web host](#without-a-web-host) +- [Trying the sample](#trying-the-sample) +- [What is not here yet](#what-is-not-here-yet) + +--- + +## Who provides what + +| Datra provides (once, for every game) | The game writes | +|---|---| +| **Knob panel**: sliders grouped and labelled from the attributes, with the saved value marked | **One attribute per tunable field**: label, group, unit, range | +| **Forked data context**: the simulator reads edited values through the ordinary `data.Floor` API; the files are never touched | (nothing) | +| **Bot runner**: N bots, one seed each, in parallel, the same result every time | **One simulator class**: how a single bot plays. It calls the game's own earnings and shop code | +| **Views**: time per stage, progression, purchase timeline, each with the comparison overlaid | (nothing — no chart code, no screen code) | +| **Result document** (JSON), targets and checks, the sentences under "Against the targets" | (optional) targets, checks, a reason only the game knows (`run.Explain`) | +| **Scenarios and snapshots**: baseline + changed knobs, saved with the result they gave | (nothing) | +| **Reader contract for stored physics outcomes** | **The outcomes**: whatever batch the game already runs, stored per physics state | +| Endpoints and the `` component | **Two lines in the host**: `AddDatraLab`, `MapDatraLab` | + +The packages: + +``` +Datra [Knob] attribute (next to [TableData], so data assemblies need nothing else) +Datra.Lab no UI: knob schema, forked context, simulator contract, bot runner, results, snapshots +Datra.WebEditor.Server AddDatraLab(), MapDatraLab() +Datra.WebEditor and the JavaScript view modules it hosts +``` + +## Adopting it + +**1. Mark the fields.** One line per knob, on the data class. + +```csharp +using Datra.Attributes; + +[SingleData("Economy.yaml")] +public partial class EconomyData +{ + [Knob("Step value", Group = "Rewards", Unit = "coins/step", Min = 1, Max = 15, Step = 0.5)] + public float StepValue { get; set; } = 5f; +} +``` + +**2. Write the simulator.** One class: a single bot, start to finish. + +```csharp +using Datra.Lab; + +public sealed class GameSim : ISimulator +{ + public void Play(GameDataContext data, SimRun run) + { + var progress = new PlayerProgress(); + foreach (var floor in data.Floor.LoadedItems.Values) + { + run.Stage(floor.Id, targetSeconds: floor.TargetMinutes * 60); // "time per stage" + while (progress.Wallet < floor.Fare && !run.OutOfTime) + { + var bottles = run.Outcome(PhysicsKeys.Of(data, progress, floor)); // a stored run + var earned = Earnings.Of(data, progress, bottles); // the game's own rule + progress.Earn(earned); + run.Tick(seconds: RunLength.Of(bottles), earned); + run.Progress(progress.Wallet / floor.Fare); // "progression" + + foreach (var offer in Bot.Pick(run.Policy, data, progress)) // the game's own shop + { + progress.Buy(offer); + run.Purchase(offer.Id, offer.Cost, group: offer.Scope); // "purchase timeline" + run.Progress(progress.Wallet / floor.Fare); + } + } + progress.Descend(); + } + } +} +``` + +**3. Add two lines to the host** (`Program.cs`), next to the editor's. + +```csharp +using Datra.WebEditor.Server; + +builder.Services.AddDatraWebEditor(o => o.DataContextType = typeof(GameDataContext)); // already there +builder.Services.AddDatraLab(lab => lab.SnapshotDirectory("lab/snapshots")); + +app.MapDatraEditor(); // already there +app.MapDatraLab(); +``` + +`AddDatraLab` reads the baseline data through the `IRawDataProvider` registered in the +container — the same one your data context is built on. + +**4. Put the screen on a page.** + +```razor + +``` + +That is the whole consumer surface. `` switches the screen's own text +to Korean; knob labels and stage names are shown as the game wrote them. + +## Knobs + +```csharp +[Knob("Pellet value", Group = "Rewards", Unit = "coins", Min = 0.5, Max = 5, Step = 0.1, + Hint = "Coins per pellet that lands in the box")] +public float PelletValue { get; set; } = 1f; +``` + +| Property | Meaning | +|---|---| +| `Group`, `Unit`, `Hint` | Heading, unit after the value, tooltip | +| `Min`, `Max`, `Step` | Slider range. Left out, the lab picks a range around the saved value | +| `Apply` | `Set` (the field becomes the value), `Scale` (multiplied, rests at 1), `Offset` (added, rests at 0) | +| `Row` | Table data: the Id of the one row the knob addresses. Empty means every row | +| `EachRow` | Table data: one knob per row, labelled `"{Label} · {Id}"` — a fare per floor | +| `Layer` | `Economy` (re-priced instantly) or `Physics` (decides stored outcomes; shown read-only in P0) | + +On table data without `Row` or `EachRow`, the knob covers every row: `Apply = Scale` multiplies +the whole column and keeps the hand-tuned ratios between rows. The attribute can be repeated on +one property, one `Row` each. + +A knob that spans several fields is declared in code: + +```csharp +builder.Services.AddDatraLab(lab => +{ + lab.Knobs(knobs => knobs.Add( + "Depth value growth", + read: data => Curves.GrowthOf(data), + write: (data, growth) => Curves.SetGrowth(data, growth), + min: 1.4, max: 3, step: 0.05, group: "Floors", unit: "×/floor")); +}); +``` + +`write` is only ever called on a forked context. Datra's analyzer (DATRA001) rejects plain +assignments to data classes, so write through `ForkedData.Set(row, r => r.Fare, value)`. + +When a scenario moves several knobs, declared knobs are applied first, then attribute knobs in +the order Set, Scale, Offset. The order the scenario lists them in does not matter. + +Knobs are numeric, top-level properties of `[TableData]` / `[SingleData]` types. Everything +else stays in the table editor; the lab does not replace it. + +## The simulator + +`Play` is called once per bot, from several threads at once, against one shared context. Keep +the class stateless, treat the data as read-only, and take all randomness from `run.Random`: +the same `run.Seed` and the same data must write the same records. + +What a simulator writes, and what is drawn from it: + +| Call | Meaning | Feeds | +|---|---|---| +| `run.Stage(id, targetSeconds, label)` | The bot enters a phase (a floor, a tier) | Time per stage, target lines | +| `run.Tick(seconds, earned, kind)` | One slice of play; advances game time | Totals, longest run | +| `run.Progress(fraction)` | How far through the phase, 0–1. May go down when spending sets the bot back | Progression | +| `run.Purchase(id, cost, group, label)` | The bot bought something | Purchase timeline | +| `run.Mark(name)` | A moment worth finding later | Result (`marks`) | +| `run.Explain(stage, text)` | A reason only the game knows | "Against the targets" | +| `run.Outcome(key)` | One stored physics outcome, drawn with this bot's randomness | — | + +Also available: `run.Policy` and `run.Param(name, fallback)` (what the bot buys and how it is +tuned — scenario settings, not game data), `run.Elapsed`, and `run.OutOfTime`. Loop on +`!run.OutOfTime` so a scenario that can never finish still returns; the bot is then reported as +unfinished instead of hanging the request. + +All times are seconds of game time. + +Policies, policy parameters and checks are declared with the lab: + +```csharp +lab.Policy("efficient", "Efficient"); +lab.Policy("cheap", "Cheapest first"); +lab.PolicyParam("shopSeconds", "Time between runs", @default: 8, min: 2, max: 30, unit: "s"); +lab.Check("First purchase", bot => bot.FirstPurchaseSeconds, "<= 60", unit: "s"); +lab.Check("Longest run", bot => bot.LongestTickSeconds("run"), "<= 90", unit: "s"); +``` + +Every comparison runs both sides with the same seeds, so the difference comes from the knobs +and not from luck. + +## Stored physics outcomes + +When the result of a run comes out of a physics engine, it cannot be recomputed while a slider +moves. The game stores outcomes per physics state ahead of time and the bots draw from them: + +```csharp +var key = PhysicsKey.Of(("floor", floor.Id), ("push", pushLevel), ("wrap", wrapLevel)); +var outcome = run.Outcome(key); +``` + +A key is the set of inputs that decide the outcome, as sorted `name=value` pairs. What goes in +is the game's business; Datra treats it as a string. + +`IOutcomeReader` is the read side, and the only side in P0: + +```csharp +public interface IOutcomeReader +{ + string Version { get; } // engine pin + recipe hash + IReadOnlyList? Pool(PhysicsKey key); // null when nothing is stored +} +``` + +`InMemoryOutcomes` holds pools in memory. `JsonlOutcomeReader(directory, version)` reads one +JSON Lines file per key, named `{key.Hash(version)}.jsonl`, one outcome per line. Set either on +`lab.Outcomes`. + +`run.Outcome` throws for a key with no stored outcomes; that bot stops and the key is listed +in the result's `problems`. `run.TryOutcome` returns false instead, for a simulator that has +an estimate to fall back on. + +## Scenarios, results, snapshots + +A **scenario** is the baseline data plus what differs from it: + +```json +{ "changes": { "FloorData[B3].Fare": 1200, "EconomyData.StepValue": 7 }, + "bots": 40, "seed": 1, "policy": "efficient", "policyParams": { "shopSeconds": 8 } } +``` + +The **baseline** is the saved data: what the raw data provider returns. The lab caches it and +re-reads it after the table editor saves or reloads (`IDataChangedNotifier`). Edits still +pending in the table editor are not part of it. + +Running a scenario forks the context (a fresh `TContext` on an overlay provider: reads fall +through to the cached baseline, writes stay in the overlay), applies the knobs to the fork, +plays the bots and aggregates. The **result** is one JSON document: `total`, `stages[]` +(median, p10, p90, target), `progression.points[]`, `purchases` (one representative bot), +`checks[]`, `marks[]`, `explains[]`, `problems[]`. The views read nothing else. + +A **snapshot** is a named scenario with the result it gave, stored as +`{directory}/{name}.json`. The result is kept so the picture survives later changes to the data +or the simulator; `baselineHash` tells whether the saved data has moved since. + +## HTTP endpoints + +`MapDatraLab()` mounts under `/api/datra/lab` and returns the route group for authorisation. + +| Method | Route | Purpose | +|---|---|---| +| GET | `/schema` | Knobs with baseline values, policies, checks, defaults | +| POST | `/run` | Scenario in, result out. `400 { "error": … }` when the scenario cannot run | +| GET | `/snapshots` | Names, newest first | +| POST | `/snapshots` | `{ "name", "scenario" }`: run it and store it with its result | +| GET | `/snapshots/{name}` | The stored scenario and result | + +The documents use the lab's own JSON shape (`LabJson`: camelCase, enum names) whatever the +host configured. + +The views are framework-free JavaScript modules (SVG, no dependencies) under +`_content/Datra.WebEditor/lab/`. They take a `source` object (`schema()`, `run()`, the snapshot +calls); `` hands them the endpoints above. + +## Without a web host + +`Datra.Lab` is netstandard2.1 and has no UI, so a console tool or a test can run the same thing: + +```csharp +var options = new LabOptions(); +options.Check("First purchase", bot => bot.FirstPurchaseSeconds, "<= 60", unit: "s"); + +var lab = new LabEngine(new FileSystemRawDataProvider("Data"), new GameSim(), options); +var result = await lab.RunAsync(new Scenario { Changes = { ["FloorData[B3].Fare"] = 1200 } }); + +File.WriteAllText("result.json", LabJson.Serialize(result, indented: true)); +``` + +`lab.ForkAsync(scenario)` returns the forked context itself, and `BotRunner.RunOne` replays a +single bot of a batch from its seed. + +## Trying the sample + +```bash +dotnet run --project Datra.WebEditor.Sample +``` + +Open . `Datra.Lab.Sample` is a toy incremental game — floors with a +fare, a fare box that is also the wallet, upgrades, everything left behind on the way down — +with a short simulator and a stand-in for a physics batch. + +## What is not here yet + +- Recomputing physics outcomes: the work queue, coarse-then-fine seeds, the "estimate" state. + Physics knobs are listed but read-only. +- Play records: overlaying recorded sessions, fitting the bots to them, replays. +- Pushing values into a running game. +- Exporting a standalone page, presentation mode, share links. +- More views (distributions, sensitivity, sweeps), A/B beyond one comparison, scenario diffs + and applying a scenario back to the data files. +- Pending table-editor edits as part of the baseline.