using System; using System.Collections.Generic; using System.Linq; using Godot; using MetaJam.Core.Content; using MetaJam.Core.Data; // Core/Content still declares its own (pre-cutover) CreatureDef and PlayerDef // POCOs — see the remark on MetaJam.Core.Data.BattleTuning. "using // MetaJam.Core.Content;" below is needed for ContentSet/ContentValidationException, // so alias the new Resource types the same way ContentLoader.cs does; an // unqualified "CreatureDef"/"PlayerDef" here would otherwise silently bind to // the old same-namespace class. using DataCreatureDef = MetaJam.Core.Data.CreatureDef; using DataPlayerDef = MetaJam.Core.Data.PlayerDef; using DataItemDef = MetaJam.Core.Data.ItemDef; namespace MetaJam.Core.Logic { ///

/// Structural validation over reference-typed content — the Phase 1 /// Database/RecipeGraph/MapGraph semantics re-expressed over Resource refs /// instead of string ids. Every failure names the offending resource's file /// path (ContentLoader stamps ResourcePath on load) and field, matching /// ContentLoader's own Fail() convention. ContentLoader.LoadAll calls these /// after building the typed ContentSet; they are also directly callable /// against hand-built in-memory resource graphs for unit tests, since /// nothing here reads from disk. /// /// What strong typing makes structurally impossible and therefore /// unvalidated here (never was a stringly id to be unknown or misspelled): /// unknown item/creature/move/location references, unknown OutputKind /// values. ///

public static class GraphChecks { // ----------------------------------------------------------------- // Recipes: DAG over ItemStack refs (cycle detection) + the // gathering/levelUp shape rules + the catalyst-tag-is-provided rule. // ----------------------------------------------------------------- public static void ValidateRecipes(ContentSet content) { if (content == null) throw new ArgumentNullException(nameof(content)); var recipes = content.Recipes?.Values ?? Enumerable.Empty(); var providedTags = ProvidedTags(content.Creatures?.Values ?? Enumerable.Empty()); var shippedStations = new HashSet(content.Stations?.Values ?? Enumerable.Empty()); // Map each produced item to the one recipe that makes it — same // "ambiguous production" guard as the old RecipeGraph.Build, now // keyed by ItemDef reference instead of a string id. var producedBy = new Dictionary(); foreach (var recipe in recipes) { if (recipe.OutputKind != OutputKind.Item || recipe.OutputItem == null) continue; if (producedBy.ContainsKey(recipe.OutputItem)) throw Fail(recipe, "outputItem", $"item '{Describe(recipe.OutputItem)}' is already produced by another recipe " + $"('{Describe(producedBy[recipe.OutputItem])}'). Ambiguous production is not supported."); producedBy[recipe.OutputItem] = recipe; } DetectRecipeCycles(producedBy); foreach (var recipe in recipes) { var inputs = recipe.Inputs ?? new Godot.Collections.Array(); if (inputs.Count == 0 && recipe.RequiredCatalystTag == null) throw Fail(recipe, "requiredCatalystTag", "has no inputs and no catalyst (free-item generation breaks the economy)."); var seenInputItems = new HashSet(); foreach (var stack in inputs) { if (stack == null || stack.Item == null) throw Fail(recipe, "inputs", "has an input stack with no item reference."); if (stack.Count <= 0) throw Fail(recipe, "inputs", $"input '{Describe(stack.Item)}' has a non-positive quantity ({stack.Count})."); // Owed rule (Task 4): two ItemStack lines naming the same // ItemDef in one recipe's Inputs is an authoring error // (should have been one line with the combined count), // not a valid row -- reject it the same loud, named way // every other shape rule here does. if (!seenInputItems.Add(stack.Item)) throw Fail(recipe, "inputs", $"has duplicate input lines for '{Describe(stack.Item)}' -- combine them into one line."); } // Task 4 (butchering): a recipe that consumes its own // catalyst needs a catalyst to consume -- ConsumesCatalyst // without RequiredCatalystTag would mean "start this with // catalyst == null" (Start's requiredCatalystTag check is the // only thing that guarantees a non-null catalyst) and then // remove a null catalyst from the roster, an authoring // mistake, not a valid row. if (recipe.ConsumesCatalyst && recipe.RequiredCatalystTag == null) throw Fail(recipe, "requiredCatalystTag", "consumes its catalyst (consumesCatalyst: true) but declares no requiredCatalystTag."); if (recipe.OutputKind == OutputKind.LevelUp) { if (recipe.OutputItem != null) throw Fail(recipe, "outputItem", "is a LevelUp recipe and must not declare an output item."); if (recipe.RequiredCatalystTag == null) throw Fail(recipe, "requiredCatalystTag", "levels up its catalyst but has no requiredCatalystTag saying who."); } else { if (recipe.OutputItem == null) throw Fail(recipe, "outputItem", "produces no item."); } if (recipe.OutputCount <= 0) throw Fail(recipe, "outputCount", $"must be > 0 (got {recipe.OutputCount})."); if (recipe.DurationSeconds < 0) throw Fail(recipe, "durationSeconds", $"must be >= 0 (got {recipe.DurationSeconds})."); if (recipe.RequiredCatalystTag != null && !providedTags.Contains(recipe.RequiredCatalystTag)) throw Fail(recipe, "requiredCatalystTag", $"requires catalyst tag '{Describe(recipe.RequiredCatalystTag)}', which no creature provides."); // Task 2 (critique B2): every recipe must declare who can work // it, and that station must actually be one this ContentSet // shipped — an "orphan" Station instance built in memory (or // belonging to a manifest section that never got loaded) is // just as much an authoring error as a dangling string id used // to be. Checked last in this per-recipe loop, deliberately: // every earlier check in this method still fires first for a // recipe that is ALSO broken some other way, so this doesn't // change what any pre-existing malformed-recipe fixture fails // with. if (recipe.Station == null) throw Fail(recipe, "station", "has no station (every recipe must declare who can work it)."); if (!shippedStations.Contains(recipe.Station)) throw Fail(recipe, "station", $"references station '{Describe(recipe.Station)}', which is not present in this " + "content set's shipped stations (orphaned reference)."); } } // ----------------------------------------------------------------- // Recipe obtainability (final-review M1 -- the general rule for // C1's class of bug): ValidateRecipes' own catalyst-tag check // (above) only asks whether SOME shipped creature carries the // required tag, including a boss-only species like cindermaw // (fire, the_wall/gym3 boss tables only). A boss encounter table // is not a renewable source -- ValidateWorld's own class doc // frames a boss block as "all or nothing," and once // BossClearedFlag is set that table stops being offered // (ExpeditionNode.TryGetForcedEncounter) forever. A recipe whose // catalyst tag is carried ONLY by boss-only species (or no // species at all) has no renewable route to a working catalyst -- // exactly the emberling/fire/burn_timber deadlock C1 found by // hand for one specific tag. This check generalizes it: every // RequiredCatalystTag must be carried by a species reachable from // at least one location's WILD encounter table (renews every // visit, never exhausted) or by the player's own starter // (PlayerDef.Starter -- always in the roster from turn one). // ----------------------------------------------------------------- public static void ValidateRecipeObtainability(ContentSet content) { if (content == null) throw new ArgumentNullException(nameof(content)); var recipes = content.Recipes?.Values ?? Enumerable.Empty(); var locations = content.World?.Locations ?? new Godot.Collections.Array(); var obtainableTags = new HashSet(); foreach (var loc in locations) { var wildCreatures = loc?.WildEncounterTable?.Creatures ?? new Godot.Collections.Array(); foreach (var creature in wildCreatures) foreach (var tag in creature?.Tags ?? new Godot.Collections.Array()) obtainableTags.Add(tag); } foreach (var tag in content.Player?.Starter?.Tags ?? new Godot.Collections.Array()) obtainableTags.Add(tag); foreach (var recipe in recipes) { if (recipe.RequiredCatalystTag == null) continue; if (!obtainableTags.Contains(recipe.RequiredCatalystTag)) throw Fail(recipe, "requiredCatalystTag", $"requires catalyst tag '{Describe(recipe.RequiredCatalystTag)}', which is carried " + "only by boss-only species (or none at all) -- a boss encounter table is not a " + "renewable source (it stops being offered once cleared), so a roster that loses its " + "last catalyst of this tag would have no way to ever work this recipe again " + "(final review C1's deadlock, generalized)."); } } // ----------------------------------------------------------------- // Equipment (Task 2): weapon/armor shape rules over EquipmentDef + // its Modifiers list. // ----------------------------------------------------------------- ///

/// Critique M5 + minor: a weapon must carry at least one modifier (an /// equippable item that does nothing is an authoring mistake, not a /// valid row), armor must never carry a SignatureMove (weapon-only, /// EquipmentDef's own doc comment) or a CombatStat.MaxHp modifier /// (that convention — "+N max HP also heals +N current HP" — only /// makes sense applied to the player's single Combatant at build /// time, never to a creature's own already-resolved MaxHp), and every /// modifier on an equipment row must be a CombatantStatModifier — the /// only modifier type Combatant.ApplyEquipment (Task 1) knows how to /// apply; a bare StatModifier (targets CreatureInstance.CurrentHp, /// pre-battle) or any other Modifier subtype here would throw at /// battle-build time instead of at content-load time. ///

public static void ValidateEquipment(ContentSet content) { if (content == null) throw new ArgumentNullException(nameof(content)); var equipment = content.Equipment?.Values ?? Enumerable.Empty(); var shipped = (content.Archetypes?.Values ?? Enumerable.Empty()).ToList(); foreach (var eq in equipment) { var modifiers = eq.Modifiers ?? new Godot.Collections.Array(); if (eq.Slot == EquipSlot.PlayerWeapon && modifiers.Count == 0) throw Fail(eq, "modifiers", "a weapon must declare at least one modifier."); if (eq.Slot == EquipSlot.CreatureArmor && eq.SignatureMove != null) throw Fail(eq, "signatureMove", "armor must not declare a signature move (weapon-only)."); // Battle plan 3 Task 5 (REQUIREMENTS 8.3): the player's combat // kit follows the WEAPON. An archetype on an armor row is a // kit nothing ever reads -- Combatant.FromPlayer takes the // weapon's and FromCreatureInstance takes the SPECIES', never // the armor's -- so it is silently inert for the whole game. if (eq.Slot == EquipSlot.CreatureArmor && eq.Archetype != null) throw Fail(eq, "archetype", "armor never carries an archetype -- the player's kit follows the WEAPON " + "(Combatant.FromPlayer), so a kit named here is read by nothing."); // ...and a weapon's kit must be one of the SHIPPED rules rows. // A `$ref` to an archetype file the manifest does not list // still resolves -- the codec loads it as a fresh instance -- // so the player would fight by a kit that is in no ContentSet, // which means ValidateArchetypes never sees it and no move's // hook is ever checked against it. Compared by REFERENCE, // because that is exactly the thing being asserted: the // interned row, not an equal copy of it. if (eq.Slot == EquipSlot.PlayerWeapon && eq.Archetype != null && !shipped.Any(kit => ReferenceEquals(kit, eq.Archetype))) throw Fail(eq, "archetype", $"names a kit ('{eq.Archetype.Name}', {eq.Archetype.GetType().Name}) that is " + "not one of the shipped data/archetypes rows. A weapon kit outside the " + "ContentSet is never validated against the moves that read it."); foreach (var modifier in modifiers) { if (!(modifier is CombatantStatModifier statMod)) throw Fail(eq, "modifiers", $"contains a modifier of type '{modifier?.GetType().Name ?? "(null)"}' — equipment " + "modifiers must be CombatantStatModifier."); if (eq.Slot == EquipSlot.CreatureArmor && statMod.Stat == CombatStat.MaxHp) throw Fail(eq, "modifiers", "armor must not carry a MaxHp modifier."); // Battle plan 6, final fix wave item 5: the TWIN of the // armor rule above, and a sharper one. A weapon comes off // MID-FIGHT -- REQUIREMENTS 8.3 makes the swap free and // any-time -- and CombatantStatModifier.Move shifts // CurrentHp by the SAME delta as MaxHp without clamping it, // while Combatant.RevertEquipment applies that delta // negated. A player on 8 HP who swaps off a +10 MaxHp // weapon lands on -2: dead, with no EffectKind.Ko beat, no // OnKo and no SaveFromKo. No shipped data/equipment row // carries one, and this keeps it that way. if (eq.Slot == EquipSlot.PlayerWeapon && statMod.Stat == CombatStat.MaxHp) throw Fail(eq, "modifiers", "a weapon must not carry a MaxHp modifier -- an in-battle swap reverts the " + "delta unclamped (CombatantStatModifier.Move), so swapping off it below the " + "delta drives CurrentHp negative with no knockout beat."); } } } ///

Depth-first cycle detection over the item-production graph /// (item -> the recipe that makes it -> its input items). Throws naming /// every item in the cycle, same shape as the old RecipeGraph.TopoSort.

private static void DetectRecipeCycles(Dictionary producedBy) { // Unvisited is 0 (TryGetValue's default out-value for a missing key), // so it needs no named constant of its own. const int InProgress = 1, Done = 2; var mark = new Dictionary(); var path = new List(); void Visit(DataItemDef item) { mark.TryGetValue(item, out var state); if (state == Done) return; if (state == InProgress) { var cycleStart = path.IndexOf(item); var cycle = path.Skip(cycleStart).Concat(new[] { item }).Select(Describe); throw new ContentValidationException("Crafting cycle detected: " + string.Join(" -> ", cycle)); } mark[item] = InProgress; path.Add(item); if (producedBy.TryGetValue(item, out var recipe)) foreach (var stack in recipe.Inputs ?? new Godot.Collections.Array()) if (stack?.Item != null) Visit(stack.Item); path.RemoveAt(path.Count - 1); mark[item] = Done; } foreach (var item in producedBy.Keys.ToList()) Visit(item); } // ----------------------------------------------------------------- // Ranch plan 2: buildables and station tiers. // ----------------------------------------------------------------- public static void ValidateBuildables(ContentSet content) { if (content == null) throw new ArgumentNullException(nameof(content)); var shippedStations = new HashSet(content.Stations?.Values ?? Enumerable.Empty()); foreach (var def in content.Buildables?.Values ?? Enumerable.Empty()) { if (string.IsNullOrEmpty(def.Name)) throw Fail(def, "name", "must be non-empty."); if (def.FootprintW < 1 || def.FootprintH < 1) throw Fail(def, "footprintW/footprintH", "must be >= 1."); if (def.GoldCost < 0) throw Fail(def, "goldCost", "must be >= 0."); foreach (var stack in def.Cost ?? new Godot.Collections.Array()) { if (stack == null || stack.Item == null) throw Fail(def, "cost", "has a cost line with no item."); if (stack.Count <= 0) throw Fail(def, "cost", $"'{Describe(stack.Item)}' has a non-positive count."); } if (def.Kind == BuildableKind.Station) { if (def.Station == null) throw Fail(def, "station", "a Station-kind buildable must reference its station."); if (shippedStations.Count > 0 && !shippedStations.Contains(def.Station)) throw Fail(def, "station", "references a station not shipped in this content set."); } else if (def.Station != null) throw Fail(def, "station", $"only Kind Station may reference a station (got {def.Kind})."); if ((def.Kind == BuildableKind.Chest || def.Kind == BuildableKind.FoodStore) && def.ChestCapacity <= 0) throw Fail(def, "chestCapacity", "a chest must hold at least one unit."); if (def.TierRequired < 1) throw Fail(def, "tierRequired", "must be >= 1."); } } public static void ValidateStationTiers(ContentSet content) { if (content == null) throw new ArgumentNullException(nameof(content)); foreach (var station in content.Stations?.Values ?? Enumerable.Empty()) foreach (var tier in station.Tiers ?? new Godot.Collections.Array()) { if (tier == null) throw Fail(station, "tiers", "contains a null tier."); if (tier.GoldCost < 0) throw Fail(station, "tiers", "goldCost must be >= 0."); foreach (var stack in tier.UpgradeCost ?? new Godot.Collections.Array()) if (stack?.Item == null || stack.Count <= 0) throw Fail(station, "tiers", "an upgradeCost line has no item or a non-positive count."); } foreach (var recipe in content.Recipes?.Values ?? Enumerable.Empty()) { if (recipe.TierRequired < 1) throw Fail(recipe, "tierRequired", "must be >= 1."); var maxTier = (recipe.Station?.Tiers?.Count ?? 0) + 1; if (recipe.TierRequired > maxTier) throw Fail(recipe, "tierRequired", $"requires tier {recipe.TierRequired} but its station only reaches tier {maxTier}."); } } // ----------------------------------------------------------------- // Ranch plan 3: zone kinds + the Zone-buildable <-> ZoneKind link. // ----------------------------------------------------------------- public static void ValidateZones(ContentSet content) { if (content == null) throw new ArgumentNullException(nameof(content)); var workTags = new HashSet((content.Creatures?.Values ?? Enumerable.Empty()) .SelectMany(c => c.WorkTags ?? new Godot.Collections.Array())); foreach (var zone in content.Zones?.Values ?? Enumerable.Empty()) { if (zone.WorkTag == null) throw Fail(zone, "workTag", "a zone kind needs a work tag."); if (workTags.Count > 0 && !workTags.Contains(zone.WorkTag)) throw Fail(zone, "workTag", $"no creature carries work tag '{zone.WorkTag.Name}' -- nobody could ever work it."); if (zone.OutputItem == null) throw Fail(zone, "outputItem", "a zone kind needs an output item."); if (zone.UnitsPerTrip < 1) throw Fail(zone, "unitsPerTrip", "must be >= 1."); if (zone.BaseMinutesPerUnit <= 0) throw Fail(zone, "baseMinutesPerUnit", "must be > 0."); if (zone.StockMax < 1) throw Fail(zone, "stockMax", "must be >= 1."); if (zone.RegrowMinutesPerUnit <= 0) throw Fail(zone, "regrowMinutesPerUnit", "must be > 0."); } foreach (var def in content.Buildables?.Values ?? Enumerable.Empty()) { if (def.Kind == BuildableKind.Zone && def.ZoneKind == null) throw Fail(def, "zoneKind", "a Zone-kind buildable must reference its zone kind."); if (def.Kind != BuildableKind.Zone && def.ZoneKind != null) throw Fail(def, "zoneKind", $"only Kind Zone may reference a zone kind (got {def.Kind})."); } } // ----------------------------------------------------------------- // World 2: the exit graph (spec §2.1). Every exit's From/To is a map // location with non-empty markers; blocker/shortcut flags ship; no two // exits from one area share a Marker; every location is reachable from // Start ignoring blockers; boss blocks are all-or-nothing; every // location has a Region and an on-disk scene; exactly one Ranch (the // Start) and exactly one Peak. // ----------------------------------------------------------------- ///

World 2 (spec §2.1): the exit graph. Every exit's From/To is a /// location in the map with non-empty Marker/ToMarker; every blocker and /// shortcut flag ships in content; no two exits from one area share a /// Marker; every location is reachable from Start ignoring blockers (a flag /// is a temporary block, an island is an authoring error); boss blocks are /// all-or-nothing; every location has a Region and a TilemapScenePath that /// exists on disk; exactly one Ranch and it is the Start; exactly one Peak. /// Scene-side marker resolution (does ToMarker exist in To's scene?) needs /// the engine and lives in NodeSystemsTest's cross-check instead.

public static void ValidateWorld(WorldMap world, IEnumerable flags) { if (world == null) throw new ArgumentNullException(nameof(world)); var locations = world.Locations ?? new Godot.Collections.Array(); var exits = world.Exits ?? new Godot.Collections.Array(); var locationSet = new HashSet(locations); var flagSet = new HashSet(flags ?? Enumerable.Empty()); if (world.Start == null || !locationSet.Contains(world.Start)) throw Fail(world, "start", "start location is not in this WorldMap's locations list."); var markersByFrom = new Dictionary>(); foreach (var exit in exits) { if (exit.From == null || !locationSet.Contains(exit.From)) throw Fail(exit, "from", "exit endpoint is not a location in this WorldMap."); if (exit.To == null || !locationSet.Contains(exit.To)) throw Fail(exit, "to", "exit endpoint is not a location in this WorldMap."); if (string.IsNullOrEmpty(exit.Marker)) throw Fail(exit, "marker", "must be non-empty."); if (string.IsNullOrEmpty(exit.ToMarker)) throw Fail(exit, "toMarker", "must be non-empty."); if (exit.Blocker != null && !flagSet.Contains(exit.Blocker)) throw Fail(exit, "blocker", $"flag '{Describe(exit.Blocker)}' is not a shipped flag."); if (exit.ShortcutFlag != null && !flagSet.Contains(exit.ShortcutFlag)) throw Fail(exit, "shortcutFlag", $"flag '{Describe(exit.ShortcutFlag)}' is not a shipped flag."); if (!markersByFrom.TryGetValue(exit.From, out var used)) markersByFrom[exit.From] = used = new HashSet(); if (!used.Add(exit.Marker)) throw Fail(exit, "marker", $"marker '{exit.Marker}' is already used by another exit from '{Describe(exit.From)}'."); } var outgoing = locations.ToDictionary(l => l, _ => new List()); foreach (var exit in exits) outgoing[exit.From].Add(exit.To); var seen = new HashSet { world.Start }; var queue = new Queue(seen); while (queue.Count > 0) foreach (var next in outgoing[queue.Dequeue()]) if (seen.Add(next)) queue.Enqueue(next); var unreachable = locations.Where(l => !seen.Contains(l)).ToList(); if (unreachable.Count > 0) throw Fail(unreachable[0], "(reachability)", $"is unreachable from the start location '{Describe(world.Start)}'."); foreach (var loc in locations) { if (loc.BossEncounterTable != null && (loc.BossMetFlag == null || loc.BossClearedFlag == null)) throw Fail(loc, "bossMetFlag/bossClearedFlag", "has a boss encounter table but is missing bossMetFlag or bossClearedFlag."); if (loc.Region == null) throw Fail(loc, "region", "every area must name a region."); if (string.IsNullOrEmpty(loc.TilemapScenePath)) throw Fail(loc, "tilemapScenePath", "every area must name its scene (World 2: every location is walked)."); var f = new File(); if (!PathResolves(f, loc.TilemapScenePath)) throw Fail(loc, "tilemapScenePath", $"'{loc.TilemapScenePath}' does not resolve to a file on disk."); // World 3: roamers live on routes only (spec 2.1 "null for // towns/gyms"). Both directions are checked -- a Route with no // table is an empty road, a Town with one is wildlife indoors. // World 5: routes AND holes carry wildlife; towns, gyms, the // ranch and the peak do not. var mayHaveSpawns = loc.Kind == AreaKind.Route || loc.Kind == AreaKind.Hole; if (mayHaveSpawns && loc.Spawns == null) throw Fail(loc, "spawns", $"a {loc.Kind} must carry a spawn table (World 3/5)."); if (!mayHaveSpawns && loc.Spawns != null) throw Fail(loc, "spawns", $"a {loc.Kind} must not carry a spawn table."); // REQUIREMENTS 4.9: a town with no inn has nowhere for its NPCs // to sleep and no way home -- both silently, so fail loudly. if (loc.Kind == AreaKind.Town && !loc.HasInn) throw Fail(loc, "hasInn", "every Town must have an inn (World 4)."); // World 5 (REQUIREMENTS 5.7): only the Ranch draws totem strays, // and every area it names must have a spawn table to draw one // from. A route with a stray pool would silently double its own // spawns; an adjacent area with no table would draw nothing. if (loc.Kind != AreaKind.Ranch && (loc.TotemAdjacent?.Count ?? 0) > 0) throw Fail(loc, "totemAdjacent", "only the Ranch may name totem-adjacent areas (World 5)."); foreach (var adjacent in loc.TotemAdjacent ?? new Godot.Collections.Array()) { if (adjacent == null) throw Fail(loc, "totemAdjacent", "has an empty entry."); if (adjacent.Spawns == null) throw Fail(loc, "totemAdjacent", $"'{Describe(adjacent)}' has no spawn table to draw a stray from."); } // World 5 (REQUIREMENTS 4.1): a dig table with no entries can // never yield anything -- an empty spot silently rewards // nothing, the "green test that isn't testing the thing" shape, // so fail loudly at load naming the area. if (loc.DigTable != null && (loc.DigTable.Entries?.Count ?? 0) == 0) throw Fail(loc, "digTable", "names a dig table with no entries."); // World 5 final review: a per-entry check, the twin of // ValidateSpawns' weight/species rule. An entry with weight <= 0 // or a null item can never be drawn (DigTable.Draw skips it and, // if every entry is like that, returns null every time) -- the // same "silently rewards nothing" shape the empty-table check // above already guards, so fail loudly at load naming the area. foreach (var entry in loc.DigTable?.Entries ?? new Godot.Collections.Array()) { if (entry == null || entry.Item == null) throw Fail(loc, "digTable", "has a dig entry with no item."); if (entry.Weight <= 0) throw Fail(loc, "digTable", $"dig entry '{Describe(entry.Item)}' has weight {entry.Weight}; must be > 0."); } // Quests plan 6 Task 7B, item 3: an INFINITE GOLD LOOP, made // impossible instead of merely absent. // // Task 5 gave a spawn-less area a TRANSIENT AreaVisitState so // the ranch dig spot works at all (WorldNode.RollOrRestore // Roamers). Transient means the row is never added to // save.AreaVisits, which means DugMarkers is empty again on the // next entry, which means the spots REFILL EVERY TIME the // player walks in. On an area WITH a spawn table the refill is // paced by RespawnWindowMinutes; with no table there is no // window to expire against and no pacing at all. // // So a sellable item in such a table is a walk-out-walk-in // money printer. Homestead's one entry is Orrin's Deed at // price 0, which is the only reason the game is safe today -- // and until now nothing enforced it. Price > 0 is exactly what // "sellable" means here: Economy.SellPrice and // DepositMath.Payout both pay 0 on a zero base price. if (loc.Spawns == null) foreach (var entry in loc.DigTable?.Entries ?? new Godot.Collections.Array()) if (entry?.Item != null && entry.Item.Price > 0) throw Fail(loc, "digTable", $"'{Describe(loc.DigTable)}' is dug on an area with no spawn table, so its spots " + $"refill on every entry; entry '{Describe(entry.Item)}' sells for {entry.Item.Price} " + "and would be an infinite gold loop. Give the area a spawn table or price the item at 0."); // World 4 (spec 2.4): every NPC placement names a real NPC and // a marker for each phase -- one posted at a marker nobody // authored would stand at the origin, silently. The placement's // own marker falls back to the def's, so either the placement // or the def must name one for each phase. foreach (var placement in loc.Npcs ?? new Godot.Collections.Array()) { if (placement == null || placement.Npc == null) throw Fail(loc, "npcs", "has a placement with no NPC."); if (string.IsNullOrEmpty(placement.DayMarker) && string.IsNullOrEmpty(placement.Npc.DayMarker)) throw Fail(loc, "npcs", $"placement of '{Describe(placement.Npc)}' names no day marker and its def has none."); if (string.IsNullOrEmpty(placement.NightMarker) && string.IsNullOrEmpty(placement.Npc.NightMarker)) throw Fail(loc, "npcs", $"placement of '{Describe(placement.Npc)}' names no night marker and its def has none."); } } var ranches = locations.Where(l => l.Kind == AreaKind.Ranch).ToList(); if (ranches.Count != 1 || ranches[0] != world.Start) throw Fail(world, "locations", $"exactly one Ranch is required and it must be the start (found {ranches.Count})."); var peaks = locations.Count(l => l.Kind == AreaKind.Peak); if (peaks != 1) throw Fail(world, "locations", $"exactly one Peak is required (found {peaks})."); var beds = locations.Count(l => l.HasBed); if (beds != 1) throw Fail(world, "locations", $"exactly one area may have the bed (found {beds})."); } // ----------------------------------------------------------------- // World 3: spawn tables. // ----------------------------------------------------------------- ///

World 3 (spec 2.2): every spawn row must be rollable and /// placeable. A zero weight can never be drawn and an empty ZoneMarker /// has nowhere to stand -- both would silently produce an EMPTY route /// rather than an error, which is exactly the "green test that isn't /// testing the thing" shape CLAUDE.md warns about.

public static void ValidateSpawns(IReadOnlyDictionary spawns) { foreach (var kv in spawns ?? new Dictionary()) { var table = kv.Value; if (table.MaxOnField <= 0) throw Fail(table, "maxOnField", $"must be > 0 (got {table.MaxOnField})."); if (table.RespawnWindowMinutes <= 0d) throw Fail(table, "respawnWindowMinutes", $"must be > 0 (got {table.RespawnWindowMinutes})."); if (table.Entries == null || table.Entries.Count == 0) throw Fail(table, "entries", "lists no spawn entries."); foreach (var entry in table.Entries) { if (entry == null || entry.Species == null) throw Fail(table, "entries", "has an entry with no species."); if (entry.Weight <= 0) throw Fail(table, "weight", $"entry '{Describe(entry.Species)}' has weight {entry.Weight}; must be > 0."); if (entry.LevelMin < 1) throw Fail(table, "levelMin", $"entry '{Describe(entry.Species)}' has levelMin {entry.LevelMin}; must be >= 1."); if (entry.LevelMax < entry.LevelMin) throw Fail(table, "levelMin", $"entry '{Describe(entry.Species)}' has levelMin {entry.LevelMin} above levelMax {entry.LevelMax}."); if (string.IsNullOrEmpty(entry.ZoneMarker)) throw Fail(table, "zoneMarker", $"entry '{Describe(entry.Species)}' names no zone marker."); if (entry.MinRegionLevel < 0) throw Fail(table, "minRegionLevel", $"entry '{Describe(entry.Species)}' has a negative minRegionLevel."); } } } // ----------------------------------------------------------------- // Encounters + player. // ----------------------------------------------------------------- public static void ValidateEncounters(IEnumerable tables) { foreach (var table in tables ?? Enumerable.Empty()) { var creatures = table.Creatures ?? new Godot.Collections.Array(); if (creatures.Count == 0) throw Fail(table, "creatures", "lists no creatures."); if (table.Level < 1) throw Fail(table, "level", $"must be >= 1 (got {table.Level})."); } } // ----------------------------------------------------------------- // Battle plan 1: the move envelope and the closed effect registry. // ----------------------------------------------------------------- ///

THE CLOSED EFFECT REGISTRY (battle spec B1 / moves spec /// 2.2): every BattleEffect primitive this build is allowed to ship, by /// name. Thirty-three, and a thirty-fourth is a SPEC CHANGE, not a task /// -- ValidateEffectRegistry below refuses one at content load, so the /// game does not boot with a primitive nobody wrote down. /// /// The moves spec's own table reads "thirty primitives"; that table /// merges four pairs onto one row each and counts `fieldInteract`, which /// is engine-side behaviour (ReachCheck) and carries no Resource. The /// plan that closed the registry said 34. Both numbers are somebody's /// arithmetic over the spec rather than a count of this build; the /// authority is the list below and the subclasses it names. /// /// A literal list, deliberately NOT derived from reflection: a registry /// computed from the classes present can never disagree with them, which /// is the one thing it exists to do.

public static readonly IReadOnlyCollection EffectRegistry = new System.Collections.ObjectModel.ReadOnlyCollection(new List { "AddStainEffect", "BlockFleeEffect", "CardEffect", "CleanseEffect", "CopyLastMoveEffect", "CounterEffect", "DamageEffect", "GestureScaleEffect", "HealEffect", "HideEffect", "InitiativeEffect", "InterruptChargeEffect", "LockStainsEffect", "MimicEffect", "ModifierNextEffect", "MoonConsumeEffect", "PostureEffect", "RankEffect", "RevealEffect", "RollEffect", "ScriptFlagEffect", "SetStateEffect", "SpendStainEffect", "SpendTokenEffect", "StatStageEffect", "StatusEffect", "SummonEffect", "SunTokenEffect", "TauntEffect", "TempoEffect", "TerrainEffect", "TwilightEffect", "WardEffect", }); ///

Every concrete BattleEffect subclass this assembly carries, /// by name -- the set ValidateEffectRegistry measures the registry /// against.

public static IEnumerable ShippedEffectTypeNames() => typeof(BattleEffect).Assembly.GetTypes() .Where(t => !t.IsAbstract && typeof(BattleEffect).IsAssignableFrom(t)) .Select(t => t.Name); ///

The registry and the build must agree, in BOTH directions: a /// primitive the build ships and the registry does not name is an /// unplanned addition, and a name the registry carries with no class /// behind it is a deletion or a rename that content can still name. /// Either one fails the content load, naming the offender. /// /// Takes the shipped names rather than reflecting for them, so it can be /// driven with a rogue set. A probe subclass is not an option: test/ and /// Core/ compile into ONE assembly in Debug, so a test-only BattleEffect /// would BE a shipped primitive and would fail this check on every /// load.

public static void ValidateEffectRegistry(IEnumerable shippedEffectTypeNames) { var shipped = new HashSet(shippedEffectTypeNames ?? Enumerable.Empty()); var registered = new HashSet(EffectRegistry); var unplanned = shipped.Except(registered).OrderBy(n => n, StringComparer.Ordinal).ToList(); if (unplanned.Count > 0) throw new ContentValidationException( "GraphChecks.EffectRegistry: this build ships BattleEffect " + (unplanned.Count == 1 ? "primitive " : "primitives ") + "the closed registry does not name: " + string.Join(", ", unplanned) + ". The registry closed at " + registered.Count + " (battle spec B1); a new " + "primitive is a spec change, not a task. Add the name to EffectRegistry in the " + "same change that adds the class."); var missing = registered.Except(shipped).OrderBy(n => n, StringComparer.Ordinal).ToList(); if (missing.Count > 0) throw new ContentValidationException( "GraphChecks.EffectRegistry: the closed registry names BattleEffect " + (missing.Count == 1 ? "primitive " : "primitives ") + "this build does not ship: " + string.Join(", ", missing) + ". A content row can still name a deleted or renamed effect, and it would fail " + "at the codec with a stack trace instead of here."); } ///

The per-ROW half of the closure: the effect on this move or /// field row must be a registered primitive, and the failure names the /// file and the slot the way every other content check does. /// /// `registry` is a parameter so a test can drive the refusal with a /// registry missing a name a shipped row really carries -- the only way /// to exercise this branch without adding a rogue BattleEffect subclass, /// which Debug's single assembly makes impossible. Null takes the real /// EffectRegistry, which is what both real doors pass.

public static void ValidateEffectIsRegistered(Resource owner, BattleEffect effect, string where, IEnumerable registry = null) { if (effect == null) return; var names = registry ?? EffectRegistry; if (names.Contains(effect.GetType().Name)) return; throw Fail(owner, where, "names '" + effect.GetType().Name + "', which the closed effect registry does " + "not carry (battle spec B1). A content row may only name a registered primitive."); } ///

The effect registry is closed BY NAME (battle spec B1): a /// content row may only name a BattleEffect subclass this build ships. /// The codec whitelist already refuses an unknown "$type", so what this /// adds is the parameter-range half -- and a named failure that points /// at the move file rather than at a codec stack trace.

public static void ValidateEffects(ContentSet content) { if (content == null) throw new ArgumentNullException(nameof(content)); // Battle plan 5 Task 5: the registry closes here. Before the rows, // because "this build ships a primitive nobody planned" is a fact // about the BUILD and would otherwise be reported as whatever row // happened to name it first. ValidateEffectRegistry(ShippedEffectTypeNames()); // Battle plan 6 Task 3: the TWIN of the requiresWeapon check in // ValidateTactics. A stave spell gated on a class no weapon row // carries is a move nobody can ever cast, and guarding the tactic // door and not the move door is this repo's signature defect. var playerWeaponClasses = new HashSet( (content.Equipment?.Values ?? Enumerable.Empty()) .Where(e => e != null && e.Slot == EquipSlot.PlayerWeapon) .Select(e => e.Class)); foreach (var kv in content.Moves ?? new Dictionary()) { var move = kv.Value; if (move.RequiresWeapon != WeaponClass.None && !playerWeaponClasses.Contains(move.RequiresWeapon)) throw Fail(move, "requiresWeapon", $"names {move.RequiresWeapon}, and no data/equipment row is a PlayerWeapon " + "of that class. The move could never be offered to anybody."); if (move.Accuracy < 1 || move.Accuracy > 100) throw Fail(move, "accuracy", $"must be 1..100 (got {move.Accuracy})."); if (move.Pp < 1) throw Fail(move, "pp", $"must be >= 1 (got {move.Pp})."); if (move.Hits < 1) throw Fail(move, "hits", $"must be >= 1 (got {move.Hits})."); if (move.Priority < -1 || move.Priority > 2) throw Fail(move, "priority", $"must be -1..+2 (got {move.Priority})."); for (var i = 0; i < move.Effects.Count; i++) { var effect = move.Effects[i]; if (effect == null) throw Fail(move, $"effects[{i}]", "is null."); ValidateEffectIsRegistered(move, effect, $"effects[{i}]"); if (effect is StatusEffect status) { if (status.Status == null) throw Fail(move, $"effects[{i}].status", "names no StatusDef."); if (status.ChancePercent < 1 || status.ChancePercent > 100) throw Fail(move, $"effects[{i}].chancePercent", $"must be 1..100 (got {status.ChancePercent})."); } // Battle plan 5 final fix wave: this rule takes the FIELD // door too (ValidateFieldEffects below). It was the last // per-effect check the move door had and the field door did // not -- the third twin-door miss on this branch. if (effect is StatStageEffect stage) ValidateStatStage(move, stage, $"effects[{i}]"); // Battle plan 5: the twin of the field-row check in // ValidateFieldEffects. A posture rider can be authored on // either a move's list or a field's, so both doors take the // same rule -- guarding one and not the other is this // repo's signature defect. if (effect is PostureEffect posture && posture.Rounds < 0) throw Fail(move, $"effects[{i}].rounds", $"must be >= 0 (got {posture.Rounds})."); // Battle plan 5 Task 2. TerrainEffect's branches are ORDERED // and each returns, so a row that sets two of them does the // first and silently drops the rest -- a Migrate that also // said "consume" would swap the fields and never eat one, and // nothing at run time would say so. Refused at load, naming // the move. if (effect is TerrainEffect terrain) ValidateTerrain(move, terrain, $"effects[{i}]"); // Battle plan 5 Task 3, and both of these take the FIELD // door too (ValidateFieldEffects below) -- guarding one door // and not the other is this repo's signature defect. if (effect is TempoEffect tempo) ValidateTempo(move, tempo, $"effects[{i}]"); if (effect is InitiativeEffect lift) ValidateInitiative(move, lift, $"effects[{i}]"); // Battle plan 5 Task 4, and both of these take the FIELD // door too (ValidateFieldEffects below). if (effect is SummonEffect summon) ValidateSummon(move, summon, $"effects[{i}]"); if (effect is SpendTokenEffect spend) ValidateSpendToken(move, spend, $"effects[{i}]"); // Battle plan 5 Task 5, and each of these takes the FIELD // door too (ValidateFieldEffects below) -- guarding one door // and not the other is this repo's signature defect, and it // is what Task 2's whole fix wave was. if (effect is BlockFleeEffect pin) ValidateBlockFlee(move, pin, $"effects[{i}]"); if (effect is ModifierNextEffect prime) ValidateModifierNext(move, prime, $"effects[{i}]"); if (effect is GestureScaleEffect gestureScale) ValidateGestureScale(move, move.Gesture, gestureScale, $"effects[{i}]"); if (effect is ScriptFlagEffect scriptFlag) ValidateScriptFlag(move, scriptFlag, content, $"effects[{i}]"); } } } ///

`statStage` (moves spec 1.3). One rule: the delta has to sit /// inside the stage band. Combatant.AddStage and SetStage clamp to /// -6..+6, so a row authored 99 silently gets 6 and the number the /// author wrote is a lie -- and a stage rider reaches the same /// Combatant.AddStage from a FIELD row as it does from a move's, so /// both doors take it.

private static void ValidateStatStage(Resource owner, StatStageEffect stage, string where) { if (stage.Delta < -6 || stage.Delta > 6) throw Fail(owner, $"{where}.delta", $"must be -6..+6 (got {stage.Delta})."); } ///

`blockFlee` (moves spec 1.3, Pin and Riptide). One rule: a /// pin has to last at least one round end. BlockFleeEffect.Resolve /// returns on anything below 1, so a row authored 0 or -1 is a move that /// pins nobody and says nothing.

private static void ValidateBlockFlee(Resource owner, BlockFleeEffect pin, string where) { if (pin.Rounds < 1) throw Fail(owner, $"{where}.rounds", $"must be >= 1 (got {pin.Rounds}); Resolve refuses anything lower, so the " + "row would be a move that pins nobody."); } ///

`modifierNext` (moves spec 1.3, the scroll riders). Two /// rules. A row that primes NOTHING -- no bonus, no double, no pierce, /// no heal -- is authored work that cannot change a fight; battle plan /// 3's fix wave took exactly that shape out of RampRules.OnHit. And a /// bonus below -100 asks for a negative multiplier, which EffectRunner /// floors at zero, so the row's own number would be a lie.

private static void ValidateModifierNext(Resource owner, ModifierNextEffect prime, string where) { if (prime.BonusPercent < -100) throw Fail(owner, $"{where}.bonusPercent", $"must be >= -100 (got {prime.BonusPercent}); -100 is already a next move " + "that does nothing, and EffectRunner floors the multiplier at zero."); if (prime.Delta == 0 && !prime.Pierce && !prime.Heals) throw Fail(owner, where, "primes nothing: bonusPercent 0, double false, pierce false, heals false. " + "The row would announce a prime the next move cannot spend."); } ///

`gestureScale` (moves spec 1.3, "any move with a gesture"). /// The percents mirror the two tuned ones and take the same ranges /// ContentLoader applies to data/tuning/battle.json, with 0 meaning /// "take the tuned value". And the rider is refused outright on a row /// with NO gesture: GestureMath.Score answers 1 for GestureKind.None /// before it ever asks for the override, so the numbers would be /// authored work that never runs.

private static void ValidateGestureScale(Resource owner, GestureKind gesture, GestureScaleEffect scale, string where) { if (scale.PerfectPercent != 0 && scale.PerfectPercent < 100) throw Fail(owner, $"{where}.perfectPercent", $"must be 0 or >= 100 (got {scale.PerfectPercent}); 0 means 'the tuned " + "gesturePerfectPercent', and a perfect gesture must never pay less than a " + "move with no gesture at all."); if (scale.MissPercent != 0 && (scale.MissPercent < 1 || scale.MissPercent > 100)) throw Fail(owner, $"{where}.missPercent", $"must be 0 or 1..100 (got {scale.MissPercent}); 0 means 'the tuned " + "gestureMissPercent'."); if (gesture == GestureKind.None) throw Fail(owner, where, "overrides the gesture multipliers on a row with no gesture. " + "GestureMath.Score answers 1 for GestureKind.None before it asks for the " + "override, so nothing here would ever be read."); } ///

`scriptFlag` (moves spec 1.3, scripted fights). The flag name /// has to be a real ProgressFlag row's NAME, because that is the only key /// the one reader uses: BattleRunner.FlagSatisfied asks /// BattleContext.ScriptFlags.Contains(flag.Name) for the ProgressFlag a /// BattleTrigger names, and SetFlagDirective -- the other writer of that /// same set -- writes exactly that. The flag still dies with the fight; /// what the row borrows is the NAMESPACE, not save progress. A raw string /// naming no flag row is a write no trigger can ever read.

private static void ValidateScriptFlag(Resource owner, ScriptFlagEffect scriptFlag, ContentSet content, string where) { if (string.IsNullOrEmpty(scriptFlag.Flag)) throw Fail(owner, $"{where}.flag", "is empty; Resolve does nothing without a name."); var known = content?.Flags?.Values.Any(f => f != null && f.Name == scriptFlag.Flag) ?? false; if (!known) throw Fail(owner, $"{where}.flag", $"names '{scriptFlag.Flag}', which is not a ProgressFlag row. " + "BattleRunner.FlagSatisfied matches a trigger's ProgressFlag by NAME, so a " + "flag no row carries can never gate anything."); } ///

The per-row checks for one `terrain` effect (moves spec /// 1.3). Split out of ValidateEffects' loop because it asks six /// questions, not one. /// /// Battle plan 5 fix wave 1: the owner is any Resource and the slot is /// a caller-supplied prefix, because a `terrain` rider can be authored /// on a MOVE's effects array or on a FIELD's entryEffects/roundEffects /// -- BattleRunner.TickFields and TerrainEffect.Resolve both call /// BattleEffect.Resolve on whatever a field row lists, so a field that /// lays a field is authorable content and takes the ordered-branch trap /// exactly as a move does. Guarding one door and not the other is this /// repo's signature defect, and it is the reason the PostureEffect /// check above already sits on both.

private static void ValidateTerrain(Resource owner, TerrainEffect terrain, string where) { if (terrain.Rounds < 0) throw Fail(owner, $"{where}.rounds", $"must be >= 0 (got {terrain.Rounds}); 0 means 'the field row's " + "own defaultRounds', and a negative reads as 0."); if (terrain.ExtendRounds < 0) throw Fail(owner, $"{where}.extendRounds", $"must be >= 0 (got {terrain.ExtendRounds}); a negative would be " + "read as 'do not extend' and the move would silently do nothing."); if (terrain.Power < 0 || terrain.PowerPerRoundRemaining < 0) throw Fail(owner, $"{where}.power/powerPerRoundRemaining", $"must both be >= 0 (got {terrain.Power} and " + $"{terrain.PowerPerRoundRemaining})."); if (terrain.Swap && (terrain.Consume || terrain.ExtendRounds > 0 || terrain.Field != null)) throw Fail(owner, $"{where}.swap", "is set alongside consume/extendRounds/field. The swap branch " + "returns first, so the rest of the row does nothing -- author one " + "terrain job per effect."); if (terrain.Consume && terrain.ExtendRounds > 0) throw Fail(owner, $"{where}.consume", "is set alongside extendRounds. The consume branch returns first, " + "so the extension never happens."); if (terrain.PowerPerRoundRemaining > 0 && !terrain.Consume) throw Fail(owner, $"{where}.powerPerRoundRemaining", "is set on an effect that does not consume a field. Only Upheave " + "has rounds to be paid for; nothing else reads this number."); } ///

The per-row checks for one `tempo` effect (moves spec 1.3, /// 2.9). TempoEffect carries FIVE jobs on one row -- rewind, act again, /// lend the player an action, delay a foe, spend the counter -- and it /// writes one beat and pays one Cost, so the rules below are all about /// a row asking for more than one thing on one payment. /// /// Split out of ValidateEffects' loop, and taking any Resource as its /// owner, because a `tempo` rider is authorable on a MOVE's effects /// array or on a FIELD row's entryEffects/roundEffects -- exactly the /// twin door ValidateTerrain grew at battle plan 5's first fix /// wave.

private static void ValidateTempo(Resource owner, TempoEffect tempo, string where) { if (tempo.Cost < 0) throw Fail(owner, $"{where}.cost", $"must be >= 0 (got {tempo.Cost}); a negative cost would PAY the " + "actor tempo for spending it, which is what delta is for."); if (tempo.SpendAll && tempo.Cost > 0) throw Fail(owner, $"{where}.spendAll", $"is set alongside cost {tempo.Cost}. Spending the whole counter and " + "charging a fixed price are two different prices for one move, and " + "the row does not say which one the player is told about -- author " + "exactly one of them."); var jobs = new List(); if (tempo.RewindHp) jobs.Add("rewindHp"); if (tempo.ActAgain) jobs.Add("actAgain"); if (tempo.PlayerActsAgain) jobs.Add("playerActsAgain"); if (tempo.DelayTarget) jobs.Add("delayTarget"); if (jobs.Count > 1) throw Fail(owner, $"{where}.{jobs[0]}", $"is set alongside {string.Join(", ", jobs.Skip(1))}. One tempo effect " + "does ONE job: it pays one cost and writes one beat, so a row asking " + "for two buys two round edits for one price and reports only the " + "first -- author one effect per job."); if (jobs.Count == 0 && tempo.Delta == 0 && !tempo.SpendAll) throw Fail(owner, $"{where}", "sets no job, no delta and no spendAll, so it does nothing at all. " + "A tempo effect either edits the round or moves the counter."); } ///

The per-row checks for one `initiative` effect (moves spec /// 1.3, 2.9 Hourglass). The twin door applies here as well, for the same /// reason it does for tempo and terrain.

private static void ValidateInitiative(Resource owner, InitiativeEffect lift, string where) { if (lift.Delta == 0) throw Fail(owner, $"{where}.delta", "must not be 0; a lift of nothing applies, occupies the combatant's " + "one lift slot for its rounds, and changes no turn order."); if (lift.Rounds < 1) throw Fail(owner, $"{where}.rounds", $"must be >= 1 (got {lift.Rounds}); turn order is fixed at the top of " + "a round, so a lift cast during one cannot touch that round at all " + "and anything below 1 buys no rounds of order whatsoever."); } ///

The per-row checks for one `summon` effect (moves spec 1.3, /// 2.10). The twin door applies here as well, for the same reason it /// does for terrain, tempo and initiative.

private static void ValidateSummon(Resource owner, SummonEffect summon, string where) { if (summon.Count < 1) throw Fail(owner, $"{where}.count", $"must be >= 1 (got {summon.Count}); a summon of nothing resolves, " + "writes the 'no more brood' beat and charges the HP cost for a " + "brood that was never asked for."); if (summon.HpCostPercent < 0 || summon.HpCostPercent > 99) throw Fail(owner, $"{where}.hpCostPercent", $"must be 0..99 (got {summon.HpCostPercent}); it is a percent of the " + "summoner's MAX hp, so 100 is a move that always fells its own " + "caster and a negative one would heal them for summoning."); } ///

The per-row checks for one `spendToken` effect (moves spec /// 1.3, 2.10). SpendTokenEffect carries THREE jobs on one row -- latch, /// intercept, carry a status -- and one token is spent once, so the /// rules below are all about a row asking for more than one thing out of /// one token.

private static void ValidateSpendToken(Resource owner, SpendTokenEffect spend, string where) { if (spend.Count < 1) throw Fail(owner, $"{where}.count", $"must be >= 1 (got {spend.Count}); a spend of no tokens does nothing " + "at all and reads as a working move."); var jobs = new List(); if (spend.Latch) jobs.Add("latch"); if (spend.Intercept) jobs.Add("intercept"); if (spend.CarryStatus != null) jobs.Add("carryStatus"); if (jobs.Count > 1) throw Fail(owner, $"{where}.{jobs[0]}", $"is set alongside {string.Join(", ", jobs.Skip(1))}. One spendToken " + "effect does ONE job with ONE token: latch consumes it, carryStatus " + "consumes it and intercept leaves it standing, so a row asking for " + "two describes two different fates for the same token -- author one " + "effect per job."); if (jobs.Count == 0) throw Fail(owner, $"{where}", "sets no job -- no latch, no intercept and no carryStatus -- so it " + "spends a token on nothing. Author the job the brood is sent to do."); } public static void ValidatePlayer(DataPlayerDef player) { if (player == null) throw new ArgumentNullException(nameof(player)); if (string.IsNullOrEmpty(player.Name)) throw Fail(player, "name", "must be non-empty."); if (player.BaseHp <= 0) throw Fail(player, "baseHp", $"must be > 0 (got {player.BaseHp})."); if (player.BaseAttack <= 0) throw Fail(player, "baseAttack", $"must be > 0 (got {player.BaseAttack})."); if (player.BaseDefense <= 0) throw Fail(player, "baseDefense", $"must be > 0 (got {player.BaseDefense})."); if (player.BaseSpeed <= 0) throw Fail(player, "baseSpeed", $"must be > 0 (got {player.BaseSpeed})."); var moves = player.Moves ?? new Godot.Collections.Array(); if (moves.Count == 0) throw Fail(player, "moves", "must list at least one move."); } // ----------------------------------------------------------------- // Leveling (Task 4): checkpoint levels strictly ascending; evolution // targets must not cycle. playerTable is optional since not every // caller (e.g. a hand-built creature-only fixture) has a player def. // ----------------------------------------------------------------- public static void ValidateLevelTables(IEnumerable creatures, LevelTable playerTable = null) { if (creatures == null) throw new ArgumentNullException(nameof(creatures)); var creatureList = creatures.ToList(); foreach (var creature in creatureList) if (creature.LevelTable != null) ValidateCheckpointsAscending(creature.LevelTable); if (playerTable != null) ValidateCheckpointsAscending(playerTable); DetectEvolutionCycles(creatureList); ValidateEvolutionTagsPreserved(creatureList); } ///

Critique B3 (load-bearing): a LevelCheckpoint.EvolvesInto target /// must carry every CreatureTag its source species carries. Checked by /// reference (tags are interned assets, same as everywhere else in this /// file -- Godot.Collections.Array<T>.Contains on a Resource element is /// reference equality, never a name comparison). Why this matters: feeding /// (data/recipes/feed_creature.json) requires the "beast" tag and /// TransformEngineNode.Start's hunger-recovery gate depends on a catalyst /// carrying it -- an evolution that silently dropped "beast" would make the /// evolved creature permanently unfeedable. Dewpetal's line also carries /// "silk", the economy's only source of that raw material -- dropping it on /// evolution would delete silk production entirely. Nothing else in this /// pipeline compares a checkpoint's two species' tag sets, so this is the /// only place either failure mode is caught, and it is caught at /// content-load time rather than discovered by a player mid-playthrough.

private static void ValidateEvolutionTagsPreserved(IEnumerable creatures) { foreach (var creature in creatures) { var sourceTags = creature.Tags ?? new Godot.Collections.Array(); var checkpoints = creature.LevelTable?.Checkpoints ?? new Godot.Collections.Array(); foreach (var checkpoint in checkpoints) { if (checkpoint.EvolvesInto == null) continue; var targetTags = checkpoint.EvolvesInto.Tags ?? new Godot.Collections.Array(); foreach (var tag in sourceTags) if (!targetTags.Contains(tag)) throw Fail(checkpoint, "evolvesInto", $"evolution target '{Describe(checkpoint.EvolvesInto)}' is missing tag " + $"'{tag.Name}' carried by source species '{Describe(creature)}' -- an " + "evolution must never strip a tag (feeding/economy invariants depend on it)."); } } } private static void ValidateCheckpointsAscending(LevelTable table) { var checkpoints = table.Checkpoints ?? new Godot.Collections.Array(); var prevLevel = 0; foreach (var checkpoint in checkpoints) { if (checkpoint.Level <= prevLevel) throw Fail(table, "checkpoints", $"checkpoint levels must be strictly ascending (level {checkpoint.Level} " + $"does not exceed {prevLevel})."); prevLevel = checkpoint.Level; } } ///

Depth-first cycle detection over the evolution graph /// (species -> every CreatureDef its table's checkpoints evolve into). /// Same shape as DetectRecipeCycles above.

private static void DetectEvolutionCycles(IEnumerable creatures) { const int InProgress = 1, Done = 2; var mark = new Dictionary(); var path = new List(); void Visit(DataCreatureDef creature) { if (creature == null) return; mark.TryGetValue(creature, out var state); if (state == Done) return; if (state == InProgress) { var cycleStart = path.IndexOf(creature); var cycle = path.Skip(cycleStart).Concat(new[] { creature }).Select(Describe); throw new ContentValidationException("Evolution cycle detected: " + string.Join(" -> ", cycle)); } mark[creature] = InProgress; path.Add(creature); foreach (var checkpoint in creature.LevelTable?.Checkpoints ?? new Godot.Collections.Array()) if (checkpoint.EvolvesInto != null) Visit(checkpoint.EvolvesInto); path.RemoveAt(path.Count - 1); mark[creature] = Done; } foreach (var creature in creatures.ToList()) Visit(creature); } // ----------------------------------------------------------------- // Scenarios (scenarios plan 1, spec S3): every scenario must build // into a legal save. Structural caps are REQUIREMENTS 3.6 (party 6, // actives 2) and 8.1 (1-5 foes); 1..100 is the level range // Leveling.StatsAt accepts at the bottom and a ceiling above every // authored table. Typed $refs already guarantee species/moves/items/ // flags/locations RESOLVE; this checks they make sense. The two // string ids a scenario carries -- RanchObjectSpec.Def and // ScenarioQuestSpec.QuestId -- get no such guarantee, so they are // resolved here, at load, naming the row. // ----------------------------------------------------------------- public const int MaxPartySize = 6; public const int MaxActives = 2; public const int MaxFoes = 5; public const int MaxScenarioLevel = 100; ///

The trinket price band (REQUIREMENTS 6: "trinkets cost 1-3 /// points"). Consts rather than tuning on purpose, and the distinction /// matters: this is the SHAPE of an authored row, the same class of /// rule as MaxPartySize above or the -6..+6 stat-stage band, and it /// never changes without the requirements changing. The two numbers a /// designer really does retune -- how many points a player and a mon /// each get -- are [Export]s on BattleTuning, read from /// data/tuning/battle.json, exactly as architecture rule 5 asks.

public const int MinTrinketCost = 1; public const int MaxTrinketCost = 3; ///

The ranch object ids a boot actually creates, read off /// RanchSeed.Rows rather than restated, so a seeded object added there /// becomes a legal ChestSpec.ObjectId with no edit here.

public static readonly HashSet SeededRanchObjectIds = new HashSet(RanchSeed.Rows.Select(row => row.Id), StringComparer.Ordinal); public static void ValidateScenarios(ContentSet content, IEnumerable scenarios) { if (content == null) throw new ArgumentNullException(nameof(content)); var worldLocations = new HashSet( content.World?.Locations ?? new Godot.Collections.Array()); foreach (var scenario in scenarios ?? Enumerable.Empty()) { if (scenario == null) throw new ContentValidationException("A null scenario reached ValidateScenarios."); var def = scenario; ContentValidationException Bad(string field, string message) => Fail(def, $"scenario '{def.Id}' / {field}", message); if (string.IsNullOrEmpty(def.Id)) throw Bad("id", "must be non-empty."); if (!string.IsNullOrEmpty(def.ResourcePath) && System.IO.Path.GetFileNameWithoutExtension(def.ResourcePath) != def.Id) throw Bad("id", $"must equal the file basename ('{def.ResourcePath}')."); if (def.Gold < 0) throw Bad("gold", $"must be >= 0 (got {def.Gold})."); if (def.Clock < 0) throw Bad("clock", $"must be >= 0 (got {def.Clock})."); if (def.PlayerLevel < 1) throw Bad("playerLevel", $"must be >= 1 (got {def.PlayerLevel})."); if (def.Party.Count > MaxPartySize) throw Bad("party", $"has {def.Party.Count} creatures; the party holds at most {MaxPartySize}."); var actives = def.Party.Count(s => s != null && s.Active); if (actives > MaxActives) throw Bad("party", $"marks {actives} creatures active; at most {MaxActives} may be active."); if (def.Party.Count + def.Ranch.Count == 0) throw Bad("party", "party and ranch are both empty -- a game never boots into an empty roster."); var seenIds = new HashSet(); ValidateCreatureSpecs(def, "party", def.Party, seenIds, Bad, content); ValidateCreatureSpecs(def, "ranch", def.Ranch, seenIds, Bad, content); ValidateCreatureSpecs(def, "box", def.Box, seenIds, Bad, content); // Battle plan 6 Task 2: ScenarioDef.PlayerTrinkets is a list of // plain string ids, the fourth such field a scenario carries. // Same rule as the per-creature one below: it must resolve, and // it must be PLAYER-scope. for (var i = 0; i < def.PlayerTrinkets.Count; i++) { var id = def.PlayerTrinkets[i]; if (string.IsNullOrEmpty(id)) throw Bad($"playerTrinkets[{i}]", "must name a trinket."); if (!content.Trinkets.TryGetValue(id, out var worn)) throw Bad($"playerTrinkets[{i}]", $"'{id}' is not a trinket in data/trinkets/."); if (worn.Scope != TrinketScope.Player) throw Bad($"playerTrinkets[{i}]", $"'{id}' is {worn.Scope}-scope; the player may only carry a Player-scope trinket."); } ValidateStacks(def.Inventory, "inventory", Bad); // ChestSpec.ObjectId is the third plain string id a scenario // carries, and scenarios plan 1 left it unchecked. It must name // a ranch object that exists, and RanchSeed.Rows is the only // thing that creates one -- RanchSeed.Apply runs on every boot, // scenario boots included. A typo is worse than a dangling // reference: RanchNode reads chests BY object id, so a // "foodstoree" row is simply never found, while RanchSeed goes // on adding the real, empty "foodstore" beside it. The scenario // then boots with a food store the author stocked and the game // reads as empty, in silence. Derived from RanchSeed.Rows, never // a copy of that list: adding a seeded object lights it up here. // // Deliberately narrow: a scenario's own `ranchObjects` rows get // generated ids ("obj1", "obj2", ...) and are NOT accepted here. // No shipped scenario authors both, and widening this to accept // them should come with the case that needs it. for (var i = 0; i < def.Chests.Count; i++) { var chest = def.Chests[i]; if (chest == null || string.IsNullOrEmpty(chest.ObjectId)) throw Bad($"chests[{i}].objectId", "must name a ranch object."); if (!SeededRanchObjectIds.Contains(chest.ObjectId)) throw Bad($"chests[{i}].objectId", $"'{chest.ObjectId}' is not a seeded ranch object id " + $"(RanchSeed.Rows: {string.Join(", ", SeededRanchObjectIds.OrderBy(id => id, StringComparer.Ordinal))})."); ValidateStacks(chest.Items, $"chests[{i}].items", Bad); } // Required, not optional. WriteFresh makes hadSave true, so a // scenario boot SKIPS the starter block that is the only code // supplying Content.Player.StartLocation -- a scenario without a // location boots into a state strictly worse than a fresh save, // with SaveGame.CurrentLocation null on every screen that reads it. if (def.Location == null) throw Bad("location", "is missing; a scenario boot never runs the starter seed that would supply one."); if (!worldLocations.Contains(def.Location)) throw Bad("location", $"'{Describe(def.Location)}' is not a location in the WorldMap."); foreach (var loc in def.VisitedLocations) if (loc == null || !worldLocations.Contains(loc)) throw Bad("visitedLocations", $"'{Describe(loc)}' is not a location in the WorldMap."); foreach (var row in def.RegionLevels) if (row?.Location == null || !worldLocations.Contains(row.Location)) throw Bad("regionLevels", $"'{Describe(row?.Location)}' is not a location in the WorldMap."); // RanchObjectSpec.Def is a BuildableDef ID held as a string, not a // "$ref" (SDD ledger row S13), so nothing else in the pipeline proves // it resolves. Catch a typo here, at load, rather than letting // ScenarioBuilder hit it later with no file name in hand. for (var i = 0; i < def.RanchObjects.Count; i++) { var placed = def.RanchObjects[i]; if (placed == null || string.IsNullOrEmpty(placed.Def)) throw Bad($"ranchObjects[{i}].def", "must name a buildable."); if (!content.Buildables.ContainsKey(placed.Def)) throw Bad($"ranchObjects[{i}].def", $"'{placed.Def}' is not a buildable in data/buildables/."); if (placed.Tier < 1) throw Bad($"ranchObjects[{i}].tier", $"must be >= 1 (got {placed.Tier})."); } // ScenarioQuestSpec.QuestId and .Status are plain strings too. for (var i = 0; i < def.Quests.Count; i++) { var questSpec = def.Quests[i]; if (questSpec == null || string.IsNullOrEmpty(questSpec.QuestId)) throw Bad($"quests[{i}].questId", "must name a quest."); if (!content.Quests.TryGetValue(questSpec.QuestId, out var quest)) throw Bad($"quests[{i}].questId", $"'{questSpec.QuestId}' is not a quest in data/quests/."); if (!Enum.IsDefined(typeof(QuestStatus), questSpec.Status ?? "")) throw Bad($"quests[{i}].status", $"'{questSpec.Status}' is not one of {string.Join("/", Enum.GetNames(typeof(QuestStatus)))}."); // StageIndex == Steps.Count is the finished quest: QuestRunner // increments past the last step and then calls Finish. if (questSpec.StageIndex < 0 || questSpec.StageIndex > quest.Steps.Count) throw Bad($"quests[{i}].stageIndex", $"is {questSpec.StageIndex}; quest '{questSpec.QuestId}' has {quest.Steps.Count} steps."); // Fix wave B: a scenario parked on a GoToStep must not START // at that step's destination. AreaScreen raises EnteredArea // on EVERY area load, a fresh boot included, so such a // scenario completes the stage it exists to demonstrate // before the player touches anything -- it lands them past // it. q6_s2_plant did exactly this: stage 1 is // GoTo(homestead) and the scenario booted at homestead. // Only an unmarked GoTo is caught, because a step naming a // Marker waits on ReachedMarker, which an area load does // not raise (R20). var parked = questSpec.StageIndex < quest.Steps.Count ? quest.Steps[questSpec.StageIndex] : null; if (parked is GoToStep goTo && string.IsNullOrEmpty(goTo.Marker) && goTo.Location != null && ReferenceEquals(goTo.Location, def.Location)) throw Bad($"quests[{i}].stageIndex", $"parks quest '{questSpec.QuestId}' on a GoToStep to '{Describe(goTo.Location)}' " + "and the scenario starts there; the area load completes the stage instantly. " + "Start the player where the previous step leaves them."); } switch (def.Launch) { case BattleLaunch battle: if (battle.Foes.Count < 1 || battle.Foes.Count > MaxFoes) throw Bad("launch.foes", $"has {battle.Foes.Count} foes; a battle needs 1..{MaxFoes}."); for (var i = 0; i < battle.Foes.Count; i++) { var foe = battle.Foes[i]; if (foe?.Species == null) throw Bad($"launch.foes[{i}].species", "is missing."); var level = ResolveLevel(def, foe.Level); if (level < 1 || level > MaxScenarioLevel) throw Bad($"launch.foes[{i}].level", $"resolves to {level}; must be 1..{MaxScenarioLevel}."); } if (!string.IsNullOrEmpty(battle.ScriptPath) && !PathResolves(null, battle.ScriptPath)) throw Bad("launch.scriptPath", $"'{battle.ScriptPath}' does not resolve to a file on disk."); break; case AreaLaunch area: if (area.Location == null || !worldLocations.Contains(area.Location)) throw Bad("launch.location", $"'{Describe(area.Location)}' is not a location in the WorldMap."); break; } } } ///

Level 0 = "use Defaults.Level" (the CreatureSpec/FoeSpec /// doc); no Defaults block = 1. Shared with ScenarioBuilder so /// validation and building cannot disagree.

public static int ResolveLevel(ScenarioDef def, int specLevel) => specLevel > 0 ? specLevel : (def?.Defaults?.Level ?? 1); ///

Species Moves plus every LevelTable checkpoint LearnedMove /// at or below the level, deduplicated by reference, in that order. /// Shared with ScenarioBuilder (the "learnset" default).

public static List LearnsetAt(DataCreatureDef species, int level) { var result = new List(); foreach (var move in species.Moves ?? new Godot.Collections.Array()) if (move != null && !result.Contains(move)) result.Add(move); foreach (var checkpoint in species.LevelTable?.Checkpoints ?? new Godot.Collections.Array()) if (checkpoint.Level <= level && checkpoint.LearnedMove != null && !result.Contains(checkpoint.LearnedMove)) result.Add(checkpoint.LearnedMove); return result; } private static void ValidateCreatureSpecs( ScenarioDef def, string field, Godot.Collections.Array specs, HashSet seenIds, Func bad, ContentSet content) { for (var i = 0; i < specs.Count; i++) { var spec = specs[i]; if (spec?.Species == null) throw bad($"{field}[{i}].species", "is missing."); var level = ResolveLevel(def, spec.Level); if (level < 1 || level > MaxScenarioLevel) throw bad($"{field}[{i}].level", $"resolves to {level}; must be 1..{MaxScenarioLevel}."); var maxHp = Leveling.StatsAt(spec.Species, level).Hp; // 0 is legal: "the party is wiped except one" is a state worth // authoring, and it is the only way a real scenario reaches // BattleSetupFor's CurrentHp > 0 filter (SDD ledger R10). if (spec.Hp != -1 && (spec.Hp < 0 || spec.Hp > maxHp)) throw bad($"{field}[{i}].hp", $"is {spec.Hp}; must be -1 (full) or 0..{maxHp} at level {level}."); if (spec.Hunger < 0f || spec.Hunger > 100f) throw bad($"{field}[{i}].hunger", $"is {spec.Hunger}; must be 0..100."); if (spec.Friendship != -1f && (spec.Friendship < 0f || spec.Friendship > 100f)) throw bad($"{field}[{i}].friendship", $"is {spec.Friendship}; must be -1 (default) or 0..100."); var learnset = LearnsetAt(spec.Species, level); foreach (var move in spec.Moves) if (move == null || !learnset.Contains(move)) throw bad($"{field}[{i}].moves", $"'{Describe(move)}' is not in {Describe(spec.Species)}'s learnset at level {level}."); if (!string.IsNullOrEmpty(spec.Id) && !seenIds.Add(spec.Id)) throw bad($"{field}[{i}].id", $"'{spec.Id}' is used by another creature in this scenario."); // Battle plan 6 Task 2: CreatureSpec.Trinket is a plain string // id, like RanchObjectSpec.Def and ScenarioQuestSpec.QuestId, // so nothing else in the pipeline proves it resolves. Caught // here, at load, rather than by ScenarioBuilder later with no // file name in hand. It also has to be a MON-scope row: a // Player trinket on a creature is a loadout no screen could // ever build. if (!string.IsNullOrEmpty(spec.Trinket)) { if (!content.Trinkets.TryGetValue(spec.Trinket, out var worn)) throw bad($"{field}[{i}].trinket", $"'{spec.Trinket}' is not a trinket in data/trinkets/."); if (worn.Scope != TrinketScope.Mon) throw bad($"{field}[{i}].trinket", $"'{spec.Trinket}' is {worn.Scope}-scope; a creature may only wear a Mon-scope trinket."); } } } private static void ValidateStacks( Godot.Collections.Array stacks, string field, Func bad) { if (stacks == null) return; for (var i = 0; i < stacks.Count; i++) { if (stacks[i]?.Item == null) throw bad($"{field}[{i}]", "has no item reference."); if (stacks[i].Count <= 0) throw bad($"{field}[{i}]", $"count must be > 0 (got {stacks[i].Count})."); } } // ----------------------------------------------------------------- // Shared helpers. // ----------------------------------------------------------------- ///

The set of creature tags at least one shipped creature /// carries. Public: ValidateRecipes uses it for the catalyst-tag-is- /// provided rule (World 2 dropped the route-tag gate that also fed on /// it -- ValidateWorld now validates blocker/shortcut flags, not tags).

public static HashSet ProvidedTags(IEnumerable creatures) => new HashSet( (creatures ?? Enumerable.Empty()) .SelectMany(c => c.Tags ?? new Godot.Collections.Array())); // ----------------------------------------------------------------- // Quests (quests plan 1, spec §2.1): ids match basenames, steps and // rewards resolve, exactly one main arc, no two quests grant the // same flag unless AllowSharedGrants. // ----------------------------------------------------------------- public static void ValidateQuests(ContentSet content) { if (content == null) throw new ArgumentNullException(nameof(content)); var quests = content.Quests ?? new Dictionary(); var grantedBy = new Dictionary(); var mainArcs = 0; var scenariosCover = QuestsWithScenarios(content); foreach (var kv in quests) { var q = kv.Value; if (string.IsNullOrEmpty(q.Id) || q.Id != kv.Key) throw Fail(q, "id", $"must equal the file basename '{kv.Key}' (got '{q.Id}')."); if (q.StartsWhen == null) throw Fail(q, "startsWhen", "every quest must declare how it starts."); if (q.Steps == null || q.Steps.Count == 0) throw Fail(q, "steps", "a quest needs at least one step."); if (q.MainArc) mainArcs++; for (var i = 0; i < q.Steps.Count; i++) { var step = q.Steps[i]; if (step == null) throw Fail(q, "steps", $"step {i} is null."); ValidateStep(content, q, step, i, scenariosCover.Contains(q.Id)); RecordGrant(grantedBy, q, step.Grants); } foreach (var reward in q.Rewards ?? new Godot.Collections.Array()) { if (reward == null) throw Fail(q, "rewards", "contains a null reward."); if (reward is ItemReward ir && (ir.Item == null || ir.Count <= 0)) throw Fail(q, "rewards", "ItemReward needs an item and a positive count."); if (reward is FlagReward fr) { if (fr.Flag == null) throw Fail(q, "rewards", "FlagReward has no flag."); RecordGrant(grantedBy, q, fr.Flag); } // Quests plan 6 Task 2: the last five reward kinds. if (reward is RecipeReward rr) { if (rr.Recipe == null) throw Fail(q, "rewards", "RecipeReward has no recipe."); // Named against the RECIPE's file, not the quest's: // the missing gate is the recipe's field, and that is // the file the author has to open. if (rr.Recipe.UnlockFlag == null) throw Fail(rr.Recipe, "unlockFlag", "a RecipeReward's recipe must declare the flag that unlocks it."); RecordGrant(grantedBy, q, rr.Recipe.UnlockFlag); } if (reward is DecorationReward dr) { if (dr.Unlocks == null || string.IsNullOrEmpty(dr.Label)) throw Fail(q, "rewards", "DecorationReward needs an unlock flag and a label."); RecordGrant(grantedBy, q, dr.Unlocks); } if (reward is GuideRevealReward gr && (gr.Species == null || string.IsNullOrEmpty(gr.Rule))) throw Fail(q, "rewards", "GuideRevealReward needs a species and a rule line."); // Battle plan 6, final fix wave item 1. TrinketId and // ScrollId are PLAIN STRING ids, so nothing else in the // pipeline proves they resolve -- the codec never reads // them as a $ref. This is the door ValidateScenarios and // ValidateCreatureSpecs already close over the SAME // trinket id space; it was built for those two callers and // left open on this twin. Two shipped quests paid for it: // broken_span named 'hibernation' and the_letter named // 'orrins_charm', neither of which is a row in // data/trinkets/, and both passed every gate because a // non-empty check is not a resolution check. if (reward is TrinketReward tr) { if (string.IsNullOrEmpty(tr.TrinketId) || string.IsNullOrEmpty(tr.Label)) throw Fail(q, "rewards", "TrinketReward needs a trinketId and a label."); if (!content.Trinkets.ContainsKey(tr.TrinketId)) throw Fail(q, "rewards", $"TrinketReward names '{tr.TrinketId}', which is not a trinket in data/trinkets/."); } if (reward is ScrollReward sr) { if (string.IsNullOrEmpty(sr.ScrollId) || string.IsNullOrEmpty(sr.Label)) throw Fail(q, "rewards", "ScrollReward needs a scrollId and a label."); if (!content.Scrolls.ContainsKey(sr.ScrollId)) throw Fail(q, "rewards", $"ScrollReward names '{sr.ScrollId}', which is not a scroll in data/scrolls/."); } } } // Message deliberately says "main arc" (a space): the shipped test // lowercases the message and asserts Contains("main arc"), which the // brief's original "mainArc" wording (no space) would have missed. if (quests.Count > 0 && mainArcs != 1) throw new ContentValidationException( $"data/quests: exactly one quest must be the main arc (mainArc = true); found {mainArcs}."); ValidateFlagGates(content); } // ----------------------------------------------------------------- // Quests plan 6 Task 7B, item 1 (ruling R24, made mechanical): a // GateStep may only require a flag something GRANTS, and a FlagStart // may only wait on one. // // Why this is a rule and not a review note: the branch that authored // the ten side quests wrote the same defect twice by hand. Quest 7 was // briefed to gate on `move_surf` and quest 10 on `move_fly` / // `peak_gate_open` -- flags nothing in the shipped content would ever // set. Both were caught by a human reading the file. Neither was caught // by a test, because the only mechanical check was that the "$ref" // resolved to a real ProgressFlag, and it did. A gate on a flag with no // granter is a PERMANENT stall: the step waits on GameEventKind.FlagSet // for an id nothing raises, the journal shows an objective the player // can never satisfy, and no error is ever printed. // ----------------------------------------------------------------- ///

One place a flag gets set, and -- when that place is inside /// a quest -- how far into that quest it is.

private sealed class FlagGrant { ///

The quest this grant lives in, or null for a grant that /// does not depend on a quest running (a Location's boss flag, a /// cutscene's SetFlagCommand).

public QuestDef Quest; ///

Step index inside Quest; RewardOrder for a grant paid /// when the quest FINISHES, which is after every step.

public int Order; } ///

Later than any step index: a quest's rewards are paid at /// completion, so a reward can never open one of its own quest's /// gates.

private const int RewardOrder = int.MaxValue; private static void ValidateFlagGates(ContentSet content) { // The guard is the WORLD MAP, not a count of anything. Most of the // shipped gates (gym1_cleared, gym2_cleared, won, ...) are granted // by a Location's bossClearedFlag/bossMetFlag and by nothing else, // so without the world the granter set is missing exactly the rows // this rule leans on and every real quest would be rejected. // QuestContentTest's and CutsceneModelTest's in-memory Set helpers // both pass world: null; ContentLoader always passes a real one. // This is the "guard on the thing you actually need, not on a // global count" trap Task 7A hit from the other side. if (content?.World == null) return; var granters = CollectFlagGrants(content); foreach (var kv in content.Quests ?? new Dictionary()) { var q = kv.Value; if (q == null) continue; // A FlagStart waits on the flag BEFORE the quest exists, so no // grant inside this same quest can ever satisfy it -- hence // order 0, which no step index (0 and up) can beat. if (q.StartsWhen is FlagStart start && start.Flag != null) RequireGranted(granters, start.Flag, q, 0, q, "startsWhen", "startsWhen (FlagStart) field 'flag'"); for (var i = 0; i < (q.Steps?.Count ?? 0); i++) if (q.Steps[i] is GateStep gate && gate.Requires != null) RequireGranted(granters, gate.Requires, q, i, q, "steps", $"step {i} (GateStep) field 'requires'"); } } ///

Every place the loaded content sets a ProgressFlag.

private static Dictionary> CollectFlagGrants(ContentSet content) { var granters = new Dictionary>(); void Add(ProgressFlag flag, QuestDef quest, int order) { if (flag == null) return; if (!granters.TryGetValue(flag, out var list)) granters[flag] = list = new List(); list.Add(new FlagGrant { Quest = quest, Order = order }); } // A boss flag is set by ExpeditionNode on a meet/clear, outside any // quest -- which is exactly why main_arc can gate on gym1_cleared. foreach (var loc in content.World.Locations ?? new Godot.Collections.Array()) { if (loc == null) continue; Add(loc.BossMetFlag, null, 0); Add(loc.BossClearedFlag, null, 0); } // A cutscene's SetFlagCommand counts as an UNCONSTRAINED granter // (quest null) even when a quest's CutsceneStep is what plays it. // Deliberately permissive: a scene can also be played by the story // manager or by another quest, and being wrong in the strict // direction here would reject shipped content. No shipped cutscene // sets a flag today, so nothing rides on the choice yet. foreach (var scene in AllReachableCutscenes(content)) foreach (var command in scene.Commands ?? new Godot.Collections.Array()) if (command is SetFlagCommand set) Add(set.Flag, null, 0); foreach (var kv in content.Quests ?? new Dictionary()) { var q = kv.Value; if (q == null) continue; for (var i = 0; i < (q.Steps?.Count ?? 0); i++) { var step = q.Steps[i]; if (step == null) continue; // Both, because they differ: FlagStep and FightStep set // CompletionFlag (Flag / WinFlag) independently of Grants. Add(step.Grants, q, i); Add(step.CompletionFlag, q, i); } foreach (var reward in q.Rewards ?? new Godot.Collections.Array()) { if (reward is FlagReward fr) Add(fr.Flag, q, RewardOrder); if (reward is DecorationReward dr) Add(dr.Unlocks, q, RewardOrder); if (reward is RecipeReward rr) Add(rr.Recipe?.UnlockFlag, q, RewardOrder); } } return granters; } ///

Fails unless some grant of can /// actually happen before the thing that waits on it. /// /// The "later in the same quest" case is a FAILURE, decided here rather /// than left ambiguous. Task 6 authored `peak_gate_open` granted by /// gate_and_peak's own step 1 and briefly gated an EARLIER step of the /// same quest on it, then moved the gate. That shape is a guaranteed /// soft-lock -- the only granter sits behind the very gate it would /// open -- and it looks completely healthy to a "$ref resolves" check /// and to a "some quest grants this" check alike. An EARLIER step of /// the same quest is fine (redundant, not broken), which is why this /// compares step order instead of just comparing quests.

private static void RequireGranted(Dictionary> granters, ProgressFlag flag, QuestDef waiter, int order, QuestDef named, string field, string where) { granters.TryGetValue(flag, out var grants); grants = grants ?? new List(); foreach (var grant in grants) if (grant.Quest == null || !ReferenceEquals(grant.Quest, waiter) || grant.Order < order) return; var name = Describe(flag); if (grants.Count > 0) throw Fail(named, field, $"{where}: '{name}' is only set later in this same quest, so this can never open. " + "Grant it from an earlier step, another quest, a boss flag or a cutscene."); throw Fail(named, field, $"{where}: nothing grants '{name}'. No quest step, no quest reward, no cutscene " + "SetFlagCommand and no Location bossMetFlag/bossClearedFlag ever sets it, so this " + "waits forever."); } ///

Quests plan 6 Task 7: the quest ids this content set carries /// at least one scenario for. It is the gate on the scenario /// cross-check in , and it has to be /// per-quest rather than a bare "are there any scenarios at all". /// /// Two shipped fixtures prove why. ScenarioTest boots a SCRATCH content /// root that keeps the real "quests" section and swaps "scenarios" for /// one or two probe files; QuestContentTest's Set helper passes no /// scenarios at all. A whole-set count guard passes the second and fails /// the first, because a partial set is not an empty one -- every shipped /// quest would then be rejected for naming a scenario the fixture never /// meant to carry. /// /// The cost: a quest with NO scenarios of its own gets no cross-check. /// QuestScenarioTest's first case is the twin that closes that gap -- it /// asserts every shipped quest has one scenario per stage.

private static HashSet QuestsWithScenarios(ContentSet content) { var covered = new HashSet(); foreach (var kv in content.Scenarios ?? new Dictionary()) foreach (var row in kv.Value?.Quests ?? new Godot.Collections.Array()) if (row != null && !string.IsNullOrEmpty(row.QuestId)) covered.Add(row.QuestId); return covered; } private static void ValidateStep(ContentSet content, QuestDef q, QuestStep step, int i, bool crossCheckScenarios) { string Where(string field) => $"step {i} ({step.GetType().Name}) field '{field}'"; switch (step) { // Shape checks only -- behaviour stays on the step classes. case GoToStep g when g.Location == null: throw Fail(q, "steps", $"{Where("location")} is null."); case FlagStep f when f.Flag == null: throw Fail(q, "steps", $"{Where("flag")} is null."); case GateStep gate when gate.Requires == null: throw Fail(q, "steps", $"{Where("requires")} is null."); case BuildStep b when !b.AnyEquipmentCraft && (b.Recipes == null || b.Recipes.Count == 0): throw Fail(q, "steps", $"{Where("recipes")} is empty and anyEquipmentCraft is false."); case FightStep fight when fight.Encounter == null && string.IsNullOrEmpty(fight.ScenarioId): throw Fail(q, "steps", $"{Where("encounter")}: needs an encounter or a scenarioId."); // Quests plan 6 Task 7: a FightStep's scenarioId is a plain // string, so a typo resolves to nothing at RUNTIME -- the step // simply never matches and the quest stalls with no error at // all. Load is the only place it can be caught. // // crossCheckScenarios is the fixture gate; see // QuestsWithScenarios above for why it is per-quest. case FightStep fs when crossCheckScenarios && !string.IsNullOrEmpty(fs.ScenarioId) && !content.Scenarios.ContainsKey(fs.ScenarioId): throw Fail(q, "steps", $"{Where("scenarioId")} names unknown scenario '{fs.ScenarioId}'."); case CutsceneStep cst when crossCheckScenarios && cst.Cutscene != null: // Same rule one level down: a cutscene a quest plays may // launch a battle by scenario id. foreach (var command in cst.Cutscene.Commands) if (command is BattleCommand bc && !string.IsNullOrEmpty(bc.ScenarioId) && !content.Scenarios.ContainsKey(bc.ScenarioId)) throw Fail(q, "steps", $"{Where("cutscene")}: '{cst.Cutscene.Id}' launches unknown scenario '{bc.ScenarioId}'."); break; case TalkStep t when t.Npc == null: throw Fail(q, "steps", $"{Where("npc")} is null."); case DeliverStep d when d.Npc == null || d.Items == null || d.Items.Count == 0: throw Fail(q, "steps", $"{Where("npc/items")}: needs an npc and at least one item."); case ShowStep s when s.Npc == null: throw Fail(q, "steps", $"{Where("npc")} is null."); case CutsceneStep c when c.Cutscene == null: throw Fail(q, "steps", $"{Where("cutscene")} is null."); // Quests plan 6 Task 1: the last seven kinds. // From is required, not optional: it is the ONLY way a downed // escort re-arms (EscortStep.Matches). An escort with no From // that goes down leaves the quest stalled with no way back -- // a soft-lock the player cannot see or undo. case EscortStep es when es.Npc == null || es.To == null || es.From == null: throw Fail(q, "steps", $"{Where("npc/from/to")}: an escort needs an NPC, a start and a destination."); // Fix wave A (finding 2), the exact twin of the marker rules // below: a phase nothing raises is the same permanent stall a // marker is. WorldNode.SleepAt is the ONLY place Slept is // raised and it always says "Morning" -- sleeping advances to // the next morning (DayCycle.OffsetToNextMorning), which is // what InnPanel promises the player in as many words. Two // shipped quests asked for "Night" and could never be // finished. DELETE THIS the moment the world plan adds a // sleep-until- capability; at that point the field // becomes useful and this rule becomes the bug. case SleepUntilStep sl when !string.IsNullOrEmpty(sl.Phase) && sl.Phase != "Morning": throw Fail(q, "steps", $"{Where("phase")} is '{sl.Phase}', but sleeping always advances to the next " + "morning -- nothing raises Slept with any other phase. Leave it empty (any " + "rest counts) or say 'Morning'."); case SleepUntilStep _: break; // an empty phase is legal: any sleep counts case ReleaseStep rs when rs.Tag == null && rs.Species == null && rs.Location == null: throw Fail(q, "steps", $"{Where("tag/species/location")}: a release step with no filter matches anything."); // --------------------------------------------------------- // Quests plan 6 Task 7B, item 2 -- the marker rules, all // three in one place because the asymmetry between them looks // like an inconsistency and is not. // // GoToStep.Marker and EscortStep.ToMarker are REJECTED when // set. Both resolve to GameEventKind.ReachedMarker, and // NOTHING in production code raises ReachedMarker -- grep // Core/, scripts/ and scenes/ and the only hits are the two // steps that consume it and GameEvent's own factory. A marker // on either step is therefore a permanent stall: the step // stops matching the EnteredArea it would otherwise take, and // waits forever on an event no code path produces. Every // shipped quest already leaves both empty (ruling R20), so // this locks in a discipline rather than changing content. // // DigStep.Marker is the opposite: REQUIRED. Its event, Dug, // really is raised -- WorldNode.Dig calls RaiseEvent("Dug", // area, marker) and Game.cs translates it into // GameEvent.Dug(id, detail). A dig with no marker matches // nothing for the same reason a GoTo WITH one matches nothing. // // DELETE THE GoTo/Escort HALF the moment the world plan raises // ReachedMarker when the player enters an AreaMarker's radius. // At that point a marker becomes the useful thing it was // designed to be, and this rule becomes the bug. // --------------------------------------------------------- case GoToStep gm when !string.IsNullOrEmpty(gm.Marker): throw Fail(q, "steps", $"{Where("marker")} is '{gm.Marker}', but nothing raises ReachedMarker -- " + "leave it empty so the step waits on EnteredArea instead."); case EscortStep em when !string.IsNullOrEmpty(em.ToMarker): throw Fail(q, "steps", $"{Where("toMarker")} is '{em.ToMarker}', but nothing raises ReachedMarker -- " + "leave it empty so the step waits on EnteredArea instead."); case DigStep ds when ds.Location == null || string.IsNullOrEmpty(ds.Marker): throw Fail(q, "steps", $"{Where("location/marker")}: a dig needs a place and a marked spot."); case HarvestStep hs when hs.Crop == null || hs.Count <= 0: throw Fail(q, "steps", $"{Where("crop/count")}: a harvest needs a crop and a positive count."); case CraftStep cs when cs.Recipe == null: throw Fail(q, "steps", $"{Where("recipe")} is null."); case BuyStep bs when bs.Item == null || bs.Count <= 0: throw Fail(q, "steps", $"{Where("item/count")}: a buy needs an item and a positive count."); } } private static void RecordGrant(Dictionary grantedBy, QuestDef q, ProgressFlag flag) { if (flag == null) return; if (grantedBy.TryGetValue(flag, out var other) && !ReferenceEquals(other, q) && !q.AllowSharedGrants && !other.AllowSharedGrants) throw Fail(q, "steps/rewards", $"grants flag '{Describe(flag)}' which '{Describe(other)}' also grants -- set allowSharedGrants on one of them if intended."); grantedBy[flag] = q; } // ----------------------------------------------------------------- // Cutscenes (quests plan 3, spec §2.4): ids match basenames, the // command list is non-empty and hole-free, dialogue paths resolve, // and an actor is spawned before it is moved/faced/animated. The // last rule is why this is a whole-list walk rather than a per // command check -- it is the one authoring mistake the runtime can // only report halfway through a scene the player is already watching. // ----------------------------------------------------------------- public static void ValidateCutscenes(ContentSet content) { if (content == null) throw new ArgumentNullException(nameof(content)); var file = new Godot.File(); foreach (var kv in content.Cutscenes ?? new Dictionary()) ValidateCutscene(file, kv.Value, kv.Key); // Quests plan 6 Task 7B, item 4 (quests-3 M2): a cutscene reached // ONLY through a CutsceneStep's "$ref" is never listed in the // manifest's "cutscenes" section, so the loop above never sees it // and it would skip every check on this page -- an unspawned actor, // a dialogue path that is not on disk, an empty command list. That // is a live shape, not a hypothetical: quests plan 6 is the first // to author quest-owned scenes, and only the manifest generator // sweeping data/cutscenes/ keeps them in the section today. // // AllReachableCutscenes de-duplicates, so a scene reachable BOTH // ways is validated once. Validating it twice would be harmless // here (the actor set is per scene) but the id check below is keyed // differently in the two paths, and a scene checked under two keys // is exactly the false conflict this avoids. foreach (var extra in QuestOnlyCutscenes(content)) ValidateCutscene(file, extra, ContentIds.Of(extra)); } ///

Every cutscene this content set can actually play: the /// manifest section plus the scenes only a quest's CutsceneStep names. /// De-duplicated by reference -- ContentLoader interns, so one file is /// one instance however many "$ref"s point at it.

private static IEnumerable AllReachableCutscenes(ContentSet content) { var seen = new List(); foreach (var kv in content.Cutscenes ?? new Dictionary()) if (kv.Value != null && !Contains(seen, kv.Value)) { seen.Add(kv.Value); yield return kv.Value; } foreach (var extra in QuestOnlyCutscenesInternal(content, seen)) yield return extra; } private static IEnumerable QuestOnlyCutscenes(ContentSet content) { var seen = new List(); foreach (var kv in content.Cutscenes ?? new Dictionary()) if (kv.Value != null) seen.Add(kv.Value); return QuestOnlyCutscenesInternal(content, seen); } private static IEnumerable QuestOnlyCutscenesInternal(ContentSet content, List seen) { foreach (var kv in content.Quests ?? new Dictionary()) { var q = kv.Value; foreach (var step in q?.Steps ?? new Godot.Collections.Array()) { if (!(step is CutsceneStep cs) || cs.Cutscene == null) continue; if (Contains(seen, cs.Cutscene)) continue; seen.Add(cs.Cutscene); yield return cs.Cutscene; } } } ///

Reference membership. Godot's Resource does not override /// Equals here, but saying so out loud beats relying on it.

private static bool Contains(List list, CutsceneDef def) { foreach (var other in list) if (ReferenceEquals(other, def)) return true; return false; } private static void ValidateCutscene(Godot.File file, CutsceneDef def, string key) { if (def == null) throw new ContentValidationException($"data/cutscenes: '{key}' is null."); if (string.IsNullOrEmpty(def.Id) || def.Id != key) throw Fail(def, "id", $"must equal the file basename '{key}' (got '{def.Id}')."); if (def.Commands == null || def.Commands.Count == 0) throw Fail(def, "commands", "a cutscene needs at least one command."); var actors = new HashSet(); // Quests plan 6 Task 7B, item 5 (quests-3 M3): the "spawned before // it is moved" rule as ONE local, so FollowCameraCommand joins it // instead of growing a second copy. FollowCamera is not an // ActorCommand (an empty ActorId legally hands the camera back to // the player), so the ActorCommand case below cannot reach it -- and // a camera told to follow a ghost fails halfway through a scene the // player is already watching. void RequireSpawned(string actorId, int index) { if (!actors.Contains(actorId)) throw Fail(def, "commands", $"command {index}: actor '{actorId}' is used before any SpawnActor for it."); } for (var i = 0; i < def.Commands.Count; i++) { var command = def.Commands[i]; if (command == null) throw Fail(def, "commands", $"command {i} is null."); switch (command) { // Shape validation over content -- a type test is the // honest tool here; behaviour stays virtual (Run). case StartDialogueCommand d when !PathResolves(file, d.DialoguePath): throw Fail(def, "commands", $"command {i}: dialoguePath '{d.DialoguePath}' does not resolve to a file on disk."); case SetFlagCommand f when f.Flag == null: throw Fail(def, "commands", $"command {i}: flag is null."); case GiveItemCommand g when g.Item == null || g.Count <= 0: throw Fail(def, "commands", $"command {i}: needs an item and a positive count."); case EnterAreaCommand e when e.Location == null: throw Fail(def, "commands", $"command {i}: location is null."); case ParticipatoryCommand p when p.Beat == null || p.Beat.Count <= 0 || p.Beat.WindowSeconds <= 0: throw Fail(def, "commands", $"command {i}: needs a beat with a positive count and window."); case BattleCommand b when string.IsNullOrEmpty(b.ScenarioId): throw Fail(def, "commands", $"command {i}: scenarioId is empty."); case SpawnActorCommand s: if (string.IsNullOrEmpty(s.ActorId) || string.IsNullOrEmpty(s.SpritePath) || string.IsNullOrEmpty(s.Marker)) throw Fail(def, "commands", $"command {i}: a spawn needs actorId, spritePath and marker."); // Item 5's twin of the StartDialogueCommand rule above: // a sprite that is not on disk draws nothing and says // nothing, mid-scene. if (!PathResolves(file, s.SpritePath)) throw Fail(def, "commands", $"command {i}: actor '{s.ActorId}' spritePath '{s.SpritePath}' does not resolve to a file on disk."); actors.Add(s.ActorId); break; case FollowCameraCommand fc when !string.IsNullOrEmpty(fc.ActorId): RequireSpawned(fc.ActorId, i); break; case ActorCommand a: RequireSpawned(a.ActorId, i); break; } if (command is DespawnActorCommand despawn) actors.Remove(despawn.ActorId); } } // ----------------------------------------------------------------- // NPCs + services (quests plan 2, spec Q6): every NPC names a // dialogue file that exists on disk, and every service's stock/ // variants/food/quests/badges are shaped so the panel that opens it // (plan 5) can never draw from an empty or contradictory row. // ----------------------------------------------------------------- public static void ValidateNpcs(ContentSet content) { if (content == null) throw new ArgumentNullException(nameof(content)); foreach (var npc in content.Npcs?.Values ?? Enumerable.Empty()) { if (string.IsNullOrEmpty(npc.Name)) throw Fail(npc, "name", "must be non-empty."); if (string.IsNullOrEmpty(npc.DialoguePath)) throw Fail(npc, "dialoguePath", "must be non-empty."); if (!PathResolves(null, npc.DialoguePath)) throw Fail(npc, "dialoguePath", $"'{npc.DialoguePath}' does not resolve to a file on disk."); if (string.IsNullOrEmpty(npc.DefaultTitle)) throw Fail(npc, "defaultTitle", "must be non-empty."); // Fix wave A, the twin of finding #6: NpcDef.Quests is the // same list shape QuestBoardService.Quests is, and it carries // the same trap -- a $ref to a quest file the manifest never // listed loads as an instance QuestRunner has never heard of. // Every shipped row is empty today; the rule lands before the // "!" icon this field drives does. CheckQuestsAreListed(npc, "quests", npc.Quests, content); // Fix wave B (ledger R47/R50). TotemPanel speaks its rungs // through ServiceContext.PlayTitle, and PlayTitle plays the // NPC's own dialogue file -- one file per NPC, the way // QuestRunner.TalkTo already reads it. TotemService names the // file its rungs are authored in, so the two have to be the // same file or the rungs are authored where no tap can reach // them. This check is what makes that field load-bearing // rather than a second, drifting owner of one path. if (npc.Service is TotemService totem && !string.IsNullOrEmpty(totem.DialoguePath) && totem.DialoguePath != npc.DialoguePath) throw Fail(npc, "dialoguePath", $"'{npc.DialoguePath}' but its badge totem authors its direction rungs in " + $"'{totem.DialoguePath}'. The totem speaks through this NPC, so both must name one file."); } foreach (var service in content.Services?.Values ?? Enumerable.Empty()) ValidateService(service, content); } ///

Every QuestDef in this list must be the very instance the /// manifest loaded (fix wave A, finding #6 and its twin). /// /// This is the content graph walked the OTHER way. A "$ref" that /// resolves proves the quest file exists; it proves nothing about the /// manifest's "quests" list containing it, and ContentLoader.GetOrLoad /// hands back a distinct instance for a file no section loaded. The /// panel would list the post and QuestRunner.Start would throw out of /// a Godot signal handler on the tap. Reference equality, not the id, /// because reference equality is what QuestRunner does.

private static void CheckQuestsAreListed( Resource owner, string field, Godot.Collections.Array quests, ContentSet content) { if (content?.Quests == null) return; foreach (var quest in quests ?? new Godot.Collections.Array()) { if (quest == null) throw Fail(owner, field, "contains a null quest."); var listed = false; foreach (var known in content.Quests.Values) if (ReferenceEquals(known, quest)) { listed = true; break; } if (!listed) throw Fail(owner, field, $"'{quest.Id}' is not in the manifest's quests list, so QuestRunner has never loaded " + "it. Add its file to data/manifest.json."); } } private static void ValidateService(ServiceDef service, ContentSet content) { // Quests plan 5 (R9): a stocked line must cost something. The // effective price is the line's own override when non-zero, else // ItemDef.Price -- and it is read through Economy.BuyPrice, the // same function the shop panel and RanchNode.Buy charge from, so // the check can never disagree with the till. A line whose item is // unpriced and whose override is 0 would put a free item on the // counter. void CheckLines(Resource owner, string field, Godot.Collections.Array lines) { foreach (var line in lines ?? new Godot.Collections.Array()) { if (line == null || line.Item == null || line.Price < 0) throw Fail(owner, field, "every line needs an item and a non-negative price."); if (Economy.BuyPrice(line) <= 0) throw Fail(owner, field, $"'{line.Item.Name}' would be free -- its line price is 0 and the item itself " + "carries no price. Give the item a price or override it on the line."); } } switch (service) { case ShopService shop: CheckLines(shop, "stock", shop.Stock); break; case SmithService smith: foreach (var v in smith.Variants ?? new Godot.Collections.Array()) { if (v == null || v.From == null || v.To == null || v.Gold < 0) throw Fail(smith, "variants", "every line needs from/to equipment and a non-negative gold cost."); // Fix wave A (finding #7): RanchNode.Forge writes // line.To straight into SaveGame.PlayerWeapon, so the // row has to obey the same slot rule // RanchNode.EquipPlayerWeapon enforces. A line forging // a sword into armor would put armor in the weapon // slot, and nothing downstream would catch it. if (v.From.Slot != EquipSlot.PlayerWeapon || v.To.Slot != EquipSlot.PlayerWeapon) throw Fail(smith, "variants", $"'{v.From.Name}' -> '{v.To.Name}': a forge line moves the player's weapon, so both " + $"sides must sit in the PlayerWeapon slot (got {v.From.Slot} -> {v.To.Slot})."); // A line that forges a weapon into itself charges gold // and hands back what the player already carries. if (ReferenceEquals(v.From, v.To)) throw Fail(smith, "variants", $"'{v.From.Name}' forges into itself."); // Fix wave A, the twin of CheckLines' free-item rule // above: Economy.VariantCost falls back to a percent // of the TARGET's own price when gold is 0, so a line // with gold 0 and an unpriced target costs nothing and // CanAfford(gold, 0) is always true -- a free rare // weapon at the smith's counter. if (v.Gold <= 0 && v.To.Price <= 0) throw Fail(smith, "variants", $"'{v.To.Name}' would be free -- the line's gold is 0 and the target carries " + "no price of its own. Give the equipment a price or name a gold cost."); } if (smith.RepairPerPoint < 0) throw Fail(smith, "repairPerPoint", "must be >= 0."); break; case InnService inn: if (inn.SleepPrice < 0) throw Fail(inn, "sleepPrice", "must be >= 0."); CheckLines(inn, "food", inn.Food); break; case QuestBoardService board: // Fix wave A (finding #6, ledger R46): walk the board's // own edge the other way, at load, naming the row. CheckQuestsAreListed(board, "quests", board.Quests, content); break; case TotemService totem: if (totem.BadgesRequired > (totem.Badges?.Count ?? 0)) throw Fail(totem, "badgesRequired", $"requires {totem.BadgesRequired} badges but lists only {totem.Badges?.Count ?? 0}."); // Fix wave B (ledger R47): TotemPanel now SPEAKS these // rungs -- DirectionTitle picks one and // ServiceContext.PlayTitle plays it out of the totem's // dialogue file. A rung with no title, or a negative // badge count no player can be under, is a totem that // stands there saying nothing, so it fails at load // naming the row instead. foreach (var direction in totem.Directions ?? new Godot.Collections.Array()) { if (direction == null) throw Fail(totem, "directions", "contains a null rung."); if (direction.Badges < 0) throw Fail(totem, "directions", $"rung at {direction.Badges} badges: a badge count must be >= 0."); if (string.IsNullOrEmpty(direction.DialogueTitle)) throw Fail(totem, "directions", $"the rung at {direction.Badges} badges names no dialogue title."); } if (string.IsNullOrEmpty(totem.DialoguePath)) throw Fail(totem, "dialoguePath", "must name the file its direction rungs are authored in."); if (!PathResolves(null, totem.DialoguePath)) throw Fail(totem, "dialoguePath", $"'{totem.DialoguePath}' does not resolve to a file on disk."); break; } } ///

Quests plan 4: the guide tier table has to be usable -- /// ascending, positive, no threshold past the species total, every /// tier carrying at least one reward (a tier that grants nothing is /// an authoring mistake, not a design choice), and every reward as /// well-formed as ValidateQuests demands of a quest's rewards.

public static void ValidateGuideTuning(GuideTuning tuning) { if (tuning == null) throw new ContentValidationException("data/tuning/guide.json: guide tuning is missing."); if (tuning.TotalSpecies <= 0) throw Fail(tuning, "totalSpecies", $"must be > 0 (got {tuning.TotalSpecies})."); if (tuning.FightsForArchetype <= 0) throw Fail(tuning, "fightsForArchetype", $"must be > 0 (got {tuning.FightsForArchetype})."); var previous = 0; foreach (var tier in tuning.Tiers ?? new Godot.Collections.Array()) { if (tier == null) throw Fail(tuning, "tiers", "contains a null tier."); if (tier.Caught <= previous) throw Fail(tuning, "tiers", $"thresholds must ascend (got {tier.Caught} after {previous})."); if (tier.Caught > tuning.TotalSpecies) throw Fail(tuning, "tiers", $"threshold {tier.Caught} is past totalSpecies {tuning.TotalSpecies}."); if (tier.Rewards == null || tier.Rewards.Count == 0) throw Fail(tuning, "tiers", $"tier at {tier.Caught} grants nothing."); if (string.IsNullOrEmpty(tier.Label)) throw Fail(tuning, "tiers", $"tier at {tier.Caught} has no label."); // Same shape as the reward loop in ValidateQuests above: a tier // grants the same Reward Resources a quest does, so it gets the // same malformed-reward checks. (Not factored into a shared // helper: the quest loop also threads RecordGrant through // FlagReward, which a tier has no equivalent of.) foreach (var reward in tier.Rewards) { if (reward == null) throw Fail(tuning, "tiers", $"tier at {tier.Caught} contains a null reward."); if (reward is ItemReward ir && (ir.Item == null || ir.Count <= 0)) throw Fail(tuning, "tiers", $"tier at {tier.Caught}: ItemReward needs an item and a positive count."); if (reward is FlagReward fr && fr.Flag == null) throw Fail(tuning, "tiers", $"tier at {tier.Caught}: FlagReward has no flag."); } previous = tier.Caught; } } ///

Quests plan 5: percentages must be percentages and costs /// must be non-negative. A sellPercent above 100 would let a player /// launder gold through a shop counter; a negative repair cost would /// pay them to break a weapon. /// /// There is no depositPercent to check here. The deposit box's cut is /// RanchTuning.DepositSalePercent (ranch plan 4), validated by /// ContentLoader.ValidateRanchTuning.

public static void ValidateEconomyTuning(EconomyTuning tuning) { if (tuning == null) throw new ContentValidationException("data/tuning/economy.json: economy tuning is missing."); void Percent(int value, string field) { if (value < 0 || value > 100) throw Fail(tuning, field, $"must be a percent 0..100 (got {value})."); } Percent(tuning.SellPercent, "sellPercent"); if (tuning.RepairPerPoint < 0) throw Fail(tuning, "repairPerPoint", $"must be >= 0 (got {tuning.RepairPerPoint})."); if (tuning.VariantMarkupPercent <= 0) throw Fail(tuning, "variantMarkupPercent", $"must be > 0 (got {tuning.VariantMarkupPercent})."); if (tuning.InnSleepPrice < 0) throw Fail(tuning, "innSleepPrice", $"must be >= 0 (got {tuning.InnSleepPrice})."); } ///

Does this res:// path resolve BOTH here and in an exported /// build? `File.FileExists` alone does not answer that. Godot imports a /// .png into `.import/<name>-<md5>.stex`, and the exported pck carries /// the .stex, not the source file -- so a portrait plainly sitting on /// disk here reports missing in the browser and the whole content load /// throws at boot, on a build every local check passed. /// /// That is not hypothetical: the SpawnActorCommand sprite check added /// in 46efc92 went green through the whole suite and then refused to /// boot the export with "res://art/portraits/wren.png does not resolve /// to a file on disk". It is this repo's oldest failure shape -- /// "works locally because of state that exists only on my disk". /// /// `ResourceLoader.Exists` follows the import remap, so it answers for /// the exported build. The literal check stays FIRST because it is the /// one that works for files shipped verbatim (.json, .tres, .tscn) and /// needs no import scan -- and a headless test run performs no import /// scan. Either one is enough; a path that is genuinely absent or /// misspelled satisfies neither and still fails loudly, naming it.

private static bool PathResolves(File file, string path) { if (string.IsNullOrEmpty(path)) return false; if ((file ?? new File()).FileExists(path)) return true; return ResourceLoader.Exists(path); } // ----------------------------------------------------------------- // Archetypes (battle spec B2, battle plan 3 Task 1). // ----------------------------------------------------------------- ///

/// Every archetype hook on a move must belong to the kit of a species /// that can learn it. /// /// A hook field the owning kit never reads is INERT at run time: the /// move loads, the fight runs, and the number simply never applies. /// That is the silent-no-op shape this codebase has been bitten by /// repeatedly, so it fails here instead, naming the move file, the /// field and the kit. Which fields a kit reads is the kit's own /// business (ArchetypeRules.HookFields), never a table in this file -- /// a field-name-to-class-name map here would have to name classes /// battle plans 4 and 5 have not written yet. /// /// Both directions are checked, because both are the same mistake: /// a hook on a move whose species has NO archetype can never be read by /// anyone, and a hook that sets another kit's field can never be read /// by this one. ///

public static void ValidateArchetypes(ContentSet content) { if (content == null) return; foreach (var kv in content.Archetypes ?? new Dictionary()) { if (string.IsNullOrEmpty(kv.Value?.Name)) throw Fail(kv.Value, "name", "an archetype needs a display name -- it is what the battle screen " + "shows beside the state indicator."); // The kit's own numbers (battle plan 5 Task 4). Asked of the kit // rather than decided here, for the reason the hook checks below // are: this file must never learn the name of a rules class. // Swarm is the first kit whose row can be authored into a kit // that silently does nothing -- maxTokens 0, tokenHp 0 -- or // into one that throws mid-fight (no tokenMove). if (kv.Value != null && !kv.Value.ValidateRow(out var rowField, out var rowProblem)) throw Fail(kv.Value, rowField, rowProblem); } foreach (var kv in content.Creatures ?? new Dictionary()) { var species = kv.Value; if (species?.Moves == null) continue; var claimed = species.Archetype == null ? new HashSet() : new HashSet(species.Archetype.HookFields ?? Enumerable.Empty()); foreach (var move in species.Moves) { if (move?.Hook == null) continue; foreach (var field in ArchetypeHook.PopulatedFields(move.Hook)) { if (claimed.Contains(field)) continue; var kit = species.Archetype == null ? $"'{species.Name}' has no archetype at all" : $"'{species.Name}' is a {species.Archetype.GetType().Name} " + $"('{species.Archetype.Name}'), which does not read it"; throw Fail(move, "hook", $"sets '{field}', but {kit}. A hook field the species' own kit " + "never reads is silently inert for the whole fight."); } // The kit's own check on the VALUES. HookFields above // answers "may this field be set at all"; this answers "is // what it is set to usable", which is the difference // between `stains: 2` on a Ramp mon and `setsState: // "Offensiv"` on a State Switch one. The second parses to // nothing, moves no state for the whole fight, and no // amount of field-ownership checking can see it. Asked of // the kit rather than decided here for the same reason the // ownership list is: this file must never learn the name of // a rules class. // The MOVE overload, not the hook one: a kit whose hook // rider can repeat what the move's own effect list already // does needs to see both halves at once. The default // implementation is the hook check, so a kit that has no // such pair is asked exactly what it was asked before. if (species.Archetype != null && !species.Archetype.ValidateHook(move, out var problem)) throw Fail(move, "hook", $"{problem} (kit: {species.Archetype.GetType().Name} " + $"'{species.Archetype.Name}' on '{species.Name}')"); } } } // ----------------------------------------------------------------- // The type x archetype matrix (battle plan 6, moves spec 1.6). // ----------------------------------------------------------------- ///

/// Every rule an authored data/moves/matrix.json row must satisfy, each /// failure naming the FILE and the row index. The matrix is the one /// content file that rewrites OTHER content: a slip here does not break /// one move, it silently changes every species that carries the family, /// the type or the kit it names. /// /// Three shapes of silence, one rule each. A rider bank with no prefix /// renames nothing, so every kit move on that whole element keeps its /// generic name. A second row for an element or a kit is never read at /// all -- MatrixResolver takes the first match. And a cell keyed on a /// family no shipped move carries is a variant that can never fire, /// which is the "green test that isn't testing the thing" in content /// form. ///

public static void ValidateMatrix(ContentSet content) { var matrix = content?.Matrix; if (matrix == null) return; var file = string.IsNullOrEmpty(matrix.ResourcePath) ? "(in-memory matrix)" : matrix.ResourcePath; // -- Table A --------------------------------------------------- var seenElements = new HashSet(); for (var i = 0; i < matrix.TypeRiders.Count; i++) { var rider = matrix.TypeRiders[i]; if (rider == null) throw new ContentValidationException($"{file}: typeRiders[{i}] is null."); if (rider.Element == Element.Neutral) throw new ContentValidationException( $"{file}: typeRiders[{i}] is Neutral. Table A has one row per TYPE " + "(spec 1.6 lists five), and a Neutral rider names no type -- it would " + "rename kit moves on a mon that has no element to give them."); if (!seenElements.Add(rider.Element)) throw new ContentValidationException( $"{file}: typeRiders[{i}] is a SECOND row for {rider.Element}. The " + "resolver takes the first match, so this one is read by nothing."); var prefixes = (rider.PrefixBank ?? "") .Split(',').Select(p => p.Trim()).Where(p => p.Length > 0).ToList(); if (prefixes.Count == 0) throw new ContentValidationException( $"{file}: typeRiders[{i}] ({rider.Element}) has an empty prefixBank. The " + "bank is what names the variant, so an empty one leaves every kit move on " + "this element carrying its generic name and nothing says so."); ValidateMatrixEffects(file, $"typeRiders[{i}].onHitEffects", rider.OnHitEffects); ValidateMatrixEffects(file, $"typeRiders[{i}].onNoHitEffects", rider.OnNoHitEffects); ValidateMatrixEffects(file, $"typeRiders[{i}].onBuffEffects", rider.OnBuffEffects); } // -- Table B --------------------------------------------------- var seenKits = new HashSet(); for (var i = 0; i < matrix.ArchetypeRows.Count; i++) { var row = matrix.ArchetypeRows[i]; if (row == null) throw new ContentValidationException($"{file}: archetypeRows[{i}] is null."); if (row.Archetype == null) throw new ContentValidationException( $"{file}: archetypeRows[{i}] names no archetype. Table B is keyed by the " + "kit, so a row with none is matched by no species."); if (!seenKits.Add(row.Archetype.GetType())) throw new ContentValidationException( $"{file}: archetypeRows[{i}] is a SECOND row for " + $"{row.Archetype.GetType().Name}. Table B is keyed on the RULES TYPE, not " + "on the resource, so the fifteen shipped data/archetypes rows share ten " + "kits -- and the resolver takes the first match, so this row is read by " + "nothing."); if (row.HeavyStrikeFrom < 1) throw new ContentValidationException( $"{file}: archetypeRows[{i}] ({row.Archetype.Name}) has heavyStrikeFrom " + $"{row.HeavyStrikeFrom}. It is a power threshold; below 1 every strike is " + "heavy and the light-strike cell is read by nothing."); } // -- the signature cells --------------------------------------- var families = new HashSet( (content.Moves ?? new Dictionary()).Values .Where(m => m != null && !string.IsNullOrEmpty(m.Family)) .Select(m => m.Family)); for (var i = 0; i < matrix.Cells.Count; i++) { var cell = matrix.Cells[i]; if (cell == null) throw new ContentValidationException($"{file}: cells[{i}] is null."); if (!string.IsNullOrEmpty(cell.Family) && families.Count > 0 && !families.Contains(cell.Family)) throw new ContentValidationException( $"{file}: cells[{i}] is keyed on the family '{cell.Family}', which no " + "shipped move carries. A cell keyed on a family nothing has can never " + "fire, and nothing at run time says so. The shipped families are " + string.Join(", ", families.OrderBy(f => f, StringComparer.Ordinal)) + "."); // 0 means "keep the base row's power" (MatrixResolver.Apply // skips it), so it is the only value outside 1..300 that is not // an authoring error. if (cell.PowerPercent != 0 && (cell.PowerPercent < 1 || cell.PowerPercent > 300)) throw new ContentValidationException( $"{file}: cells[{i}] has powerPercent {cell.PowerPercent}; it must be " + "1..300 (0 means 'keep the base row's power'). A percent outside the band " + "is a variant nobody balanced."); ValidateMatrixEffects(file, $"cells[{i}].riders", cell.Riders); } } ///

The per-effect rules a matrix rider takes. ValidateEffects /// walks content.Moves, and a matrix rider is on NEITHER door it knows /// about -- not a move's effects, not a field's -- so the same checks /// are asked here. The third door, and this repo's signature defect is /// guarding one and not another.

private static void ValidateMatrixEffects( string file, string where, Godot.Collections.Array effects) { if (effects == null) return; for (var i = 0; i < effects.Count; i++) { var effect = effects[i]; if (effect == null) throw new ContentValidationException($"{file}: {where}[{i}] is null."); if (!EffectRegistry.Contains(effect.GetType().Name)) throw new ContentValidationException( $"{file}: {where}[{i}] names '{effect.GetType().Name}', which the closed " + "effect registry does not carry (battle spec B1)."); if (effect is StatusEffect status) { if (status.Status == null) throw new ContentValidationException( $"{file}: {where}[{i}] names no StatusDef."); if (status.ChancePercent < 1 || status.ChancePercent > 100) throw new ContentValidationException( $"{file}: {where}[{i}].chancePercent must be 1..100 (got " + $"{status.ChancePercent})."); } if (effect is StatStageEffect stage && (stage.Delta < -6 || stage.Delta > 6)) throw new ContentValidationException( $"{file}: {where}[{i}].delta must be -6..+6 (got {stage.Delta}); " + "Combatant.AddStage clamps, so a bigger number is a lie."); } } // ----------------------------------------------------------------- // Terrain (battle plan 5, moves spec 2.7). // ----------------------------------------------------------------- ///

/// Every rule an authored FieldDef row must satisfy, each failure naming /// the field FILE and the offending property. A field edits what every /// other move on the table does, so an authoring slip here is invisible /// in play: a row with a 0 element bonus simply never boosts anything, /// and a row that forces Grounded is a Gale that lifts nobody. Both look /// exactly like a field that is working. ///

public static void ValidateFields(ContentSet content) { if (content == null) return; foreach (var kv in content.Fields ?? new Dictionary()) { var field = kv.Value; if (field == null) throw new ContentValidationException( $"data/fields: the row '{kv.Key}' loaded as null."); if (string.IsNullOrEmpty(field.Name)) throw Fail(field, "name", "a field needs a display name -- it is what the battle screen shows " + "over the painted floor."); // A field that lasts no rounds is laid and gone in the same // breath; the spec's every row is three. if (field.DefaultRounds < 1) throw Fail(field, "defaultRounds", $"must be >= 1 (got {field.DefaultRounds}). A field that lasts no " + "rounds is laid and expires before anyone stands on it."); // The bonus is a MULTIPLIER percent, so 0 silently zeroes every // hit of the field's own element -- the opposite of what the row // is for. 100 (no bonus) is legal; below it is not. if (field.ElementBonusPercent < 100) throw Fail(field, "elementBonusPercent", $"must be >= 100 (got {field.ElementBonusPercent}). It multiplies a " + "move of the field's own element; below 100 a field PUNISHES its own " + "type, which no row in moves spec 2.7 does."); // The two posture fields are a pair. ForcesPosture with a // Grounded override is a Gale that lifts nobody, and it reads // exactly like a working row. if (field.ForcesPosture && field.PostureOverride == Posture.Grounded) throw Fail(field, "postureOverride", "is Grounded while forcesPosture is true, so the field forces the " + "posture everyone already has and does nothing. Set a posture, or " + "clear forcesPosture."); if (field.DefenceStageForElement < -6 || field.DefenceStageForElement > 6) throw Fail(field, "defenceStageForElement", $"must be -6..+6 (got {field.DefenceStageForElement}) -- it is a stat " + "STAGE, and Combatant.SetStage clamps to that range."); ValidateFieldEffects(field, field.EntryEffects, "entryEffects", content); ValidateFieldEffects(field, field.RoundEffects, "roundEffects", content); } } ///

The per-effect half of ValidateFields, over one of the two /// arrays. Deliberately the same rules ValidateEffects applies to a /// move's list: a null hole NullReferenceExceptions inside the runner /// whichever array it sits in. /// /// Battle plan 6 Task 2 widened `owner` from FieldDef to Resource and /// gave this body a THIRD door: a TrinketDef's own Effects array. /// Sharing the body rather than copying it is the point -- guarding one /// door and not its twin is this repo's signature defect, and it was /// battle plan 5's defect three separate times. A rule added here now /// reaches every authored effect list in the game at once.

private static void ValidateFieldEffects( Resource owner, Godot.Collections.Array effects, string where, ContentSet content) { for (var i = 0; i < (effects?.Count ?? 0); i++) { var effect = effects[i]; if (effect == null) throw Fail(owner, $"{where}[{i}]", "is null."); ValidateEffectIsRegistered(owner, effect, $"{where}[{i}]"); if (effect is StatusEffect status) { if (status.Status == null) throw Fail(owner, $"{where}[{i}].status", "names no StatusDef."); if (status.ChancePercent < 1 || status.ChancePercent > 100) throw Fail(owner, $"{where}[{i}].chancePercent", $"must be 1..100 (got {status.ChancePercent})."); } // Battle plan 5 final fix wave: the ELEVENTH move-door rule, and // the one this door was still missing. A `statStage` rider on a // field row reaches Combatant.AddStage through the very same // BattleEffect.Resolve a move's does, and AddStage clamps to 6 // -- so `delta: 99` loaded clean here while the identical rider // on a move row was refused naming the slot. if (effect is StatStageEffect stage) ValidateStatStage(owner, stage, $"{where}[{i}]"); if (effect is PostureEffect posture && posture.Rounds < 0) throw Fail(owner, $"{where}[{i}].rounds", $"must be >= 0 (got {posture.Rounds})."); // Battle plan 5 fix wave 1: the terrain rules take the field // door too. A `terrain` rider on a field row resolves through // the very same BattleEffect.Resolve the move door reaches, so // the contradictory combinations do the same silent nothing // here -- see ValidateTerrain's remark. if (effect is TerrainEffect terrain) ValidateTerrain(owner, terrain, $"{where}[{i}]"); // Battle plan 5 Task 3: the tempo rules take the field door // too, for the reason the terrain rules do -- BattleRunner // .TickFields and TerrainEffect.Resolve both call // BattleEffect.Resolve on whatever a field row lists. if (effect is TempoEffect tempo) ValidateTempo(owner, tempo, $"{where}[{i}]"); if (effect is InitiativeEffect lift) ValidateInitiative(owner, lift, $"{where}[{i}]"); // Battle plan 5 Task 4: the summon rules take the field door // too, for the reason the terrain and tempo rules do -- a field // row's effects resolve through the very same // BattleEffect.Resolve a move's do. if (effect is SummonEffect summon) ValidateSummon(owner, summon, $"{where}[{i}]"); if (effect is SpendTokenEffect spend) ValidateSpendToken(owner, spend, $"{where}[{i}]"); // Battle plan 5 Task 5: the last three rules take the field door // too, for the reason every rule above them does -- a field row's // effects resolve through the very same BattleEffect.Resolve a // move's do. if (effect is BlockFleeEffect pin) ValidateBlockFlee(owner, pin, $"{where}[{i}]"); if (effect is ModifierNextEffect prime) ValidateModifierNext(owner, prime, $"{where}[{i}]"); // A field carries no gesture at all, so GestureKind.None is not // an approximation here: a gestureScale on a field row is always // authored work nothing can read, and the shared rule says so in // the same words the move door uses. if (effect is GestureScaleEffect gestureScale) ValidateGestureScale(owner, GestureKind.None, gestureScale, $"{where}[{i}]"); // ...and the FOURTH of the new authorable riders, which the // comment above once called "the last three" while quietly // skipping this one. A scriptFlag on a field row reaches // BattleContext.ScriptFlags through the very same // BattleEffect.Resolve a move's does, and BattleRunner // .FlagSatisfied matches a trigger's ProgressFlag by NAME -- so // a field row naming no flag row writes a key no trigger can // ever read, silently, exactly as a move row would. Guarding // one door and not its twin is this repo's signature defect, // and it is the reason every rule above this line takes both. if (effect is ScriptFlagEffect scriptFlag) ValidateScriptFlag(owner, scriptFlag, content, $"{where}[{i}]"); } } // ----------------------------------------------------------------- // Trinkets (REQUIREMENTS 6, moves spec 5.1 and 5.3; battle plan 6 // Task 2). // ----------------------------------------------------------------- ///

/// The trinket rows' shape rules. Every failure names the FILE, the /// same convention every check in this class follows -- data/trinkets/ /// is a brand-new data/ subdirectory and this is the fifth of the five /// things ruling B-5 asks of one. /// /// Four rules: /// /// 1. Cost 1..3 (REQUIREMENTS 6, "trinkets cost 1-3 points"). A 0-cost /// trinket is free build power the budget cannot price; a 4-cost one /// is beyond every budget in the game. /// 2. A Player/Mon trinket must not carry a RanchModifier, and a Ranch /// trinket must not carry battle Effects. Either combination is /// authored work that nothing will ever read: the battle layer never /// looks at RanchModifier and the ranch plans never resolve a /// BattleEffect. /// 3. The cost must fit the SCOPE'S OWN BUDGET, read off BattleTuning /// (TrinketPlayerPoints / TrinketMonPoints, from /// data/tuning/battle.json). A Mon row costing 4 when the mon budget /// is 3 is a trinket no creature could ever equip. This is the rule /// that proves the tuned number is READ rather than merely stored -- /// architecture rule 5, and battle plan 5 lost two fix waves to /// balance numbers living in C#. /// 4. Its Effects go through the same per-effect body a move's and a /// field's do (ValidateFieldEffects), so a rule added for one door /// reaches all three. ///

public static void ValidateTrinkets(ContentSet content) { if (content == null) return; foreach (var kv in content.Trinkets ?? new Dictionary()) { var trinket = kv.Value; if (trinket == null) throw new ContentValidationException( $"data/trinkets: the row '{kv.Key}' loaded as null."); if (string.IsNullOrEmpty(trinket.Name)) throw Fail(trinket, "name", "a trinket needs a display name -- it is what the loadout screen shows."); if (trinket.Cost < MinTrinketCost || trinket.Cost > MaxTrinketCost) throw Fail(trinket, "cost", $"must be {MinTrinketCost}..{MaxTrinketCost} (got {trinket.Cost}); " + "REQUIREMENTS 6 prices every trinket in that band."); if (trinket.Scope == TrinketScope.Ranch) { if ((trinket.Effects?.Count ?? 0) > 0) throw Fail(trinket, "effects", "is non-empty on a Ranch-scope trinket. The ranch plans never resolve " + "a BattleEffect, so these would be authored work nothing reads; a " + "ranch trinket carries a ranchModifier instead."); } else { if (trinket.RanchModifier != null) throw Fail(trinket, "ranchModifier", $"is set on a {trinket.Scope}-scope trinket. The battle layer never " + "reads a RanchModifier, so it would be authored work nothing reads; " + "set scope to Ranch, or carry effects instead."); var budget = TrinketRunner.PointsFor(trinket.Scope, content.Battle); if (budget > 0 && trinket.Cost > budget) throw Fail(trinket, "cost", $"is {trinket.Cost} and the {trinket.Scope} budget is {budget} " + "(BattleTuning.Trinket" + trinket.Scope + "Points, from " + "data/tuning/battle.json), so nothing could ever equip it."); } ValidateFieldEffects(trinket, trinket.Effects, "effects", content); } } // ----------------------------------------------------------------- // Player tactics (REQUIREMENTS 8.2, moves spec 4, battle plan 6 Task 3). // ----------------------------------------------------------------- ///

/// Every rule an authored data/tactics/*.json row must satisfy, each /// failure naming the FILE and the field. Ruling B-5's fifth thing for /// the brand-new data/tactics/ directory. /// /// An EMPTY effects list is LEGAL and is not a mistake: data/tactics /// /swap.json ships inert on purpose, because "put a reserve on the /// field without spending that mon's action" is the one tactic no /// combination of the closed 33-primitive registry can express, and /// ruling B-1 forbids a 34th. A row with nothing in it still gets a /// name, a cooldown and a button. ///

public static void ValidateTactics(ContentSet content) { if (content == null) return; // Which weapon classes the game actually ships. A tactic gated on a // class no weapon row carries is a button nobody can ever press -- // the same class of silence a matrix cell keyed on a family no move // carries is, and it is caught here for the same reason. var shippedClasses = new HashSet( (content.Equipment?.Values ?? Enumerable.Empty()) .Where(e => e != null && e.Slot == EquipSlot.PlayerWeapon) .Select(e => e.Class)); foreach (var kv in content.Tactics ?? new Dictionary()) { var tactic = kv.Value; if (tactic == null) throw new ContentValidationException( $"data/tactics: the row '{kv.Key}' loaded as null."); if (string.IsNullOrEmpty(tactic.Name)) throw Fail(tactic, "name", "a tactic needs a display name -- it is what the battle menu shows."); if (string.IsNullOrEmpty(tactic.Text)) throw Fail(tactic, "text", "a tactic needs its one line of text (moves spec 4 gives every tactic " + "one); an unexplained button is a mechanic the player cannot learn."); if (tactic.CooldownRounds < 0) throw Fail(tactic, "cooldownRounds", $"must be >= 0 (got {tactic.CooldownRounds}); a negative cooldown counts " + "UP at every round start and the tactic never comes back."); if (tactic.RequiresWeapon != WeaponClass.None && !shippedClasses.Contains(tactic.RequiresWeapon)) throw Fail(tactic, "requiresWeapon", $"names {tactic.RequiresWeapon}, and no data/equipment row is a " + "PlayerWeapon of that class. The tactic could never be offered to " + "anybody."); ValidateFieldEffects(tactic, tactic.Effects, "effects", content); } } // ----------------------------------------------------------------- // Move scrolls (moves spec 1.8, battle plan 6 Task 4). // ----------------------------------------------------------------- ///

/// Every rule an authored data/scrolls/*.json row must satisfy, each /// failure naming the FILE and the field. Ruling B-5's fifth thing for /// the brand-new data/scrolls/ directory. /// /// Every rule here answers the same question: could a shipped mon /// actually USE what this scroll sells? A scroll is bought with gold /// and spent for good, so "it taught something inert" is the worst /// outcome the content can have, and none of the four ways to get there /// is visible at run time. /// /// 1. It must teach a move, and a move THIS CONTENT SET HAS. A dangling /// Taught is an item that costs gold and does nothing. /// 2. The taught move must not be WEAPON-GATED (ruling T4-A1). A mon /// carries WeaponClass.None and BattleRunner.Perform throws on the /// mismatch, so a scroll teaching a stave spell teaches a move the /// runner refuses out loud. Refused BY RULE rather than by the /// author's care in picking, because the shipped move list already /// holds five of them. /// 3. Every ArchetypeHook field the taught move sets must be a field /// the scroll's own ArchetypeGate kit READS. That is exactly the /// rule ValidateArchetypes applies to a species learnset, one door /// over -- and the door a scroll opens is the only other way a move /// reaches a mon. A hook field the mon's kit never reads is inert /// for the whole fight; a hook with no gate at all is worse, because /// it is inert on every mon that could buy it. The kit is then asked /// about the VALUES too (ArchetypeRules.ValidateHook), which is the /// difference between 'stains: 2' on a Ramp mon and /// 'setsState: "Offensiv"' on a State Switch one. /// 4. SOME shipped creature must satisfy every gate at once. An Air /// gate on a Bulwark scroll is unteachable if no Air mon carries the /// Bulwark kit, and nothing at run time says so -- the scroll simply /// sits in the bag and every mon refuses it. The same shape /// ValidateTactics catches for a weapon class no equipment row /// carries. ///

public static void ValidateScrolls(ContentSet content) { if (content == null) return; var moves = new HashSet(content.Moves?.Values ?? Enumerable.Empty()); var creatures = (content.Creatures?.Values ?? Enumerable.Empty()) .Where(c => c != null).ToList(); foreach (var kv in content.Scrolls ?? new Dictionary()) { var scroll = kv.Value; if (scroll == null) throw new ContentValidationException( $"data/scrolls: the row '{kv.Key}' loaded as null."); if (string.IsNullOrEmpty(scroll.Name)) throw Fail(scroll, "name", "a scroll needs a display name -- it is what the shop shelf and the " + "bag show, and ShopPanel keys its rows on it."); if (scroll.Taught == null) throw Fail(scroll, "taught", "a scroll must name the move it teaches. A scroll that teaches nothing " + "is an item the player buys, spends, and gets nothing for."); if (!moves.Contains(scroll.Taught)) throw Fail(scroll, "taught", $"names '{Describe(scroll.Taught)}', which is not a move in this content " + "set. A scroll may only teach a row the game itself ships."); if (scroll.Taught.RequiresWeapon != WeaponClass.None) throw Fail(scroll, "taught", $"names '{scroll.Taught.Name}', which requires a " + $"{scroll.Taught.RequiresWeapon}. A mon carries {WeaponClass.None}, and " + "BattleRunner.Perform throws on a weapon-gate mismatch -- so this scroll " + "would teach a move its owner can never use."); var gateFields = scroll.ArchetypeGate == null ? new HashSet() : new HashSet( scroll.ArchetypeGate.HookFields ?? Enumerable.Empty()); foreach (var field in ArchetypeHook.PopulatedFields(scroll.Taught.Hook)) { if (gateFields.Contains(field)) continue; var kit = scroll.ArchetypeGate == null ? "this scroll carries no archetypeGate at all" : $"this scroll's gate is a {scroll.ArchetypeGate.GetType().Name} " + $"('{scroll.ArchetypeGate.Name}'), which does not read it"; throw Fail(scroll, "taught", $"teaches '{scroll.Taught.Name}', whose hook sets '{field}', but " + $"{kit}. A hook field the taught mon's kit never reads is silently " + "inert for the whole fight, so gate the scroll on the kit that reads " + "it."); } if (scroll.ArchetypeGate != null && !scroll.ArchetypeGate.ValidateHook(scroll.Taught, out var problem)) throw Fail(scroll, "taught", $"teaches '{scroll.Taught.Name}', and {problem} (gate: " + $"{scroll.ArchetypeGate.GetType().Name} '{scroll.ArchetypeGate.Name}')"); if (!creatures.Any(c => Teachable(scroll, c))) { var gates = new List(); if (!scroll.AnyElement) gates.Add($"element {scroll.ElementGate}"); if (scroll.ArchetypeGate != null) gates.Add($"archetype '{scroll.ArchetypeGate.Name}'"); throw Fail(scroll, "gates", "no shipped data/creatures row satisfies " + (gates.Count == 0 ? "this scroll (the content set ships no creature at all)" : string.Join(" + ", gates)) + ". Nobody could ever be taught it, so it is gold spent on nothing."); } } } ///

Whether one species passes every gate a scroll carries. /// Reference equality on the archetype, never a type test: the scroll /// row and the species row both come from the same interned ContentSet, /// and this file must never learn a rules class's name (the archetype /// dispatch scan).

private static bool Teachable(ScrollDef scroll, DataCreatureDef species) { if (species == null) return false; if (!scroll.AnyElement && species.Element != scroll.ElementGate) return false; if (scroll.ArchetypeGate != null && species.Archetype != scroll.ArchetypeGate) return false; return true; } // ----------------------------------------------------------------- // Battle scripts (battle spec 4.5, battle plan 2 Task 4). // ----------------------------------------------------------------- ///

/// Every rule an authored BattleScript must satisfy, each failure /// naming the script FILE and the trigger. Content, not code, decides /// when a beat fires, so an authoring mistake here has to be a boot /// error -- a trigger that never matches anything is otherwise /// invisible, and "the cutscene did not play" is the least useful /// possible bug report. ///

public static void ValidateBattleScripts(ContentSet content) { if (content == null) throw new ArgumentNullException(nameof(content)); var cutscenes = content.Cutscenes ?? new Dictionary(); var flags = new HashSet(content.Flags?.Values ?? Enumerable.Empty()); foreach (var script in content.BattleScripts?.Values ?? Enumerable.Empty()) { if (script == null) continue; for (var i = 0; i < script.Triggers.Count; i++) { var trigger = script.Triggers[i]; var where = $"triggers[{i}]"; if (trigger == null) throw Fail(script, where, "is null."); var named = string.IsNullOrEmpty(trigger.Name) ? where : $"{where} ('{trigger.Name}')"; if (string.IsNullOrEmpty(trigger.Name)) throw Fail(script, where + ".name", "must be non-empty -- it is what the screen keys a beat on."); if (UnfiredEvents.Contains(trigger.When)) throw Fail(script, named + ".when", $"'{trigger.When}' is declared but not yet fired by BattleRunner (see " + "BattleEvent for the plan that owns it). A trigger on it would never run."); if (!string.IsNullOrEmpty(trigger.CutsceneId) && !cutscenes.ContainsKey(trigger.CutsceneId)) throw Fail(script, named + ".cutsceneId", $"'{trigger.CutsceneId}' is not a cutscene in this content set."); if (trigger.HpBelowPercent < 0 || trigger.HpBelowPercent > 100) throw Fail(script, named + ".hpBelowPercent", $"must be 0..100 (0 = any); got {trigger.HpBelowPercent}."); if (trigger.Actor == TriggerActor.FoeIndex && (trigger.FoeIndex < 0 || trigger.FoeIndex > 4)) throw Fail(script, named + ".foeIndex", $"must be 0..4 when actor is FoeIndex; got {trigger.FoeIndex}."); // Controller ruling R31: the save-side flag reader defaults // to "nothing is set", so a RequiresFlag naming a flag this // content set does not ship can never be satisfied from the // save -- the trigger would be silently dead. if (trigger.RequiresFlag != null && !flags.Contains(trigger.RequiresFlag)) throw Fail(script, named + ".requiresFlag", $"'{Describe(trigger.RequiresFlag)}' is not a flag in this content set."); for (var d = 0; d < trigger.Directives.Count; d++) ValidateDirective(script, $"{named}.directives[{d}]", trigger.Directives[d]); } } } ///

The BattleEvent values battle plan 7 owns. The runner /// declares them so that plan needs no content-breaking enum bump, and /// never fires them -- so a script must not name one. /// /// Still all three after battle plan 7 Task 2. Capture AND running both /// RESOLVE in the runner now, but neither ResolveCapture nor /// ResolveFlee raises an event, so a trigger on any of the three would /// still never run and this list must keep refusing it. See /// BattleEvent's own comment. /// /// OnArchetypeStateChange was the fourth until battle plan 3 Task 2 and /// is deliberately NOT here any more: SetStateEffect and the State /// Switch kit move a state, BattleRunner.FireArchetypeStateChanges /// fires the event for it, so an authored trigger on it now runs. These /// two are twins (controller ruling R12) -- firing without dropping it /// here leaves authored content unable to hook the event this plan /// exists to raise, and dropping it without firing lets a script sit /// silently dead. Both moved in the same change.

private static readonly HashSet UnfiredEvents = new HashSet { BattleEvent.OnCaptureAttempt, BattleEvent.OnCaptureSuccess, BattleEvent.OnRunAttempt, }; private static void ValidateDirective(BattleScript script, string where, BattleDirective directive) { if (directive == null) throw Fail(script, where, "is null."); // Every reference a directive cannot act without, and every AUTHORED // foe index. Both shapes die SILENTLY at run time by design: each // directive's Apply guards and returns, so a missing species means // the wave simply never arrives and a stray index means the override // never lands. BattleDirectives.cs's guard-style comment says that // is safe "because content load already shouted" -- so this is where // the shouting has to happen, and it must cover the whole set. // // It did not. Until battle plan 2 Task 4 fix 1 this checked three // species fields and nothing else, so `ForceIntentDirective // { foeIndex: 9 }` loaded clean and then no-opped for the entire // fight with nothing said at either end. // // The index range is 0..4, the same rule the trigger-level foeIndex // above uses, because five foes is the widest the screen lays out. switch (directive) { case AddFoeDirective addFoe when addFoe.Species == null: throw Fail(script, where + ".species", "an AddFoeDirective needs a species."); case AddAllyDirective addAlly when addAlly.Species == null: throw Fail(script, where + ".species", "an AddAllyDirective needs a species."); // Index first, then the reference, in all four cases below: a // directive missing both reports one field, and which one it is // must not depend on the directive kind. case SwapFoeDirective swapFoe: RequireFoeIndex(script, where, "SwapFoeDirective", swapFoe.FoeIndex); if (swapFoe.Species == null) throw Fail(script, where + ".species", "a SwapFoeDirective needs a species."); break; case ForceIntentDirective forceIntent: RequireFoeIndex(script, where, "ForceIntentDirective", forceIntent.FoeIndex); if (forceIntent.Move == null) throw Fail(script, where + ".move", "a ForceIntentDirective needs a move."); break; case SetPolicyDirective setPolicy: RequireFoeIndex(script, where, "SetPolicyDirective", setPolicy.FoeIndex); if (setPolicy.Policy == null) throw Fail(script, where + ".policy", "a SetPolicyDirective needs a policy."); break; case HealCombatantDirective heal: // The index is only meaningful when the heal names one foe // by index; every other TriggerActor ignores the field // entirely, so an unused stray must not fail the load. if (heal.Actor == TriggerActor.FoeIndex) RequireFoeIndex(script, where, "HealCombatantDirective", heal.FoeIndex); // The twin that missed the round above (final whole-branch // review, Minor 3). Apply returns silently on a // non-positive percent and the field has NO default, so // {"$type":"HealCombatantDirective","actor":"AnyFoe"} // loaded clean and then no-opped for the whole fight with // nothing said at either end -- the exact shape this block // exists to close. if (heal.PercentOfMax <= 0) throw Fail(script, where + ".percentOfMax", "a HealCombatantDirective's percentOfMax must be greater " + $"than 0; got {heal.PercentOfMax}."); break; case EquipPlayerWeaponDirective equip when equip.Equipment == null: throw Fail(script, where + ".equipment", "an EquipPlayerWeaponDirective needs an equipment row."); case GrantItemDirective grant when grant.Item == null: throw Fail(script, where + ".item", "a GrantItemDirective needs an item."); case SetFlagDirective setFlag when setFlag.Flag == null: throw Fail(script, where + ".flag", "a SetFlagDirective needs a flag."); } } ///

The one shape every directive's foe index is checked in, so /// the four call sites cannot drift apart.

private static void RequireFoeIndex(BattleScript script, string where, string kind, int foeIndex) { if (foeIndex < 0 || foeIndex > 4) throw Fail(script, where + ".foeIndex", $"a {kind}'s foeIndex must be 0..4; got {foeIndex}."); } private static ContentValidationException Fail(Resource resource, string field, string message) { var path = resource?.ResourcePath; var name = string.IsNullOrEmpty(path) ? "(in-memory resource)" : path; return new ContentValidationException($"{name}: field '{field}': {message}"); } private static string Describe(Resource resource) { if (resource == null) return "(none)"; return string.IsNullOrEmpty(resource.ResourcePath) ? resource.GetType().Name : resource.ResourcePath; } // ----------------------------------------------------------------- // Ranch plan 4: crops. // ----------------------------------------------------------------- public static void ValidateCrops(ContentSet content) { if (content == null) throw new ArgumentNullException(nameof(content)); foreach (var crop in content.Crops?.Values ?? Enumerable.Empty()) { if (string.IsNullOrEmpty(crop.Name)) throw Fail(crop, "name", "must be non-empty."); if (crop.Seed == null) throw Fail(crop, "seed", "a crop needs a seed item."); if (crop.Produce == null) throw Fail(crop, "produce", "a crop needs a produce item."); if (ReferenceEquals(crop.Seed, crop.Produce)) throw Fail(crop, "produce", "seed and produce are the same item -- planting would be a no-op loop."); if (crop.ProduceCount < 1) throw Fail(crop, "produceCount", "must be >= 1."); if (crop.GrowMinutes <= 0f) throw Fail(crop, "growMinutes", "must be > 0."); if (crop.WaterMinutesPerVisit <= 0f) throw Fail(crop, "waterMinutesPerVisit", "must be > 0."); // Quests plan 5 (R9): ItemDef.Price 0 means "not traded at // all". An unpriced seed cannot be stocked by any shop, so the // crop is unreachable; an unpriced harvest cannot be sold or // deposited, so growing it pays nothing. Either one silently // breaks the farming loop, which is why it is a load error and // not a balance note. if (crop.Seed.Price <= 0) throw Fail(crop, "seed", $"crop '{crop.Name}': seed '{crop.Seed.Name}' has no price, so no shop can stock it " + "and the crop is unreachable."); if (crop.Produce.Price <= 0) throw Fail(crop, "produce", $"crop '{crop.Name}': produce '{crop.Produce.Name}' has no price, so the harvest " + "cannot be sold or deposited."); } // A CropBed buildable with no storage could never hold its own // seeds or take its own harvest (RanchNode plants and harvests // through the bed's chest row). foreach (var def in content.Buildables?.Values ?? Enumerable.Empty()) if (def.Kind == BuildableKind.CropBed && def.ChestCapacity <= 0) throw Fail(def, "chestCapacity", "a crop bed needs storage -- seeds go in and the harvest comes out of its own chest."); } // ----------------------------------------------------------------- // Ranch plan 5: raid tuning. // ----------------------------------------------------------------- public static void ValidateRaidTuning(RaidTuning t) { if (t == null) throw new ArgumentNullException(nameof(t)); if (t.CadenceMinutes <= 0f) throw Fail(t, "cadenceMinutes", "must be > 0 -- a zero cadence would schedule every future raid at the same instant."); if (t.FirstRaidDelayMinutes < 0f) throw Fail(t, "firstRaidDelayMinutes", "must be >= 0."); if (t.BaseStrength < 1) throw Fail(t, "baseStrength", "must be >= 1."); if (t.WaveCount < 1) throw Fail(t, "waveCount", "must be >= 1 (the boss wave is one of them)."); if (t.WaveFoeCount < 1) throw Fail(t, "waveFoeCount", "must be >= 1."); if (t.BossStatMultiplier < 1f) throw Fail(t, "bossStatMultiplier", "must be >= 1."); if (t.FoeStrengthPerLevel < 1) throw Fail(t, "foeStrengthPerLevel", "must be >= 1."); if (t.DefenderStrengthPerLevel < 1) throw Fail(t, "defenderStrengthPerLevel", "must be >= 1."); if (t.FriendshipStrengthPercent < 0f) throw Fail(t, "friendshipStrengthPercent", "must be >= 0."); if (t.DefenderDeathChancePercent < 0 || t.DefenderDeathChancePercent > 100) throw Fail(t, "defenderDeathChancePercent", "must be in [0, 100]."); if (t.StockpileLossPercent < 0 || t.StockpileLossPercent > 100) throw Fail(t, "stockpileLossPercent", "must be in [0, 100]."); if (t.RaidLogMax < 1) throw Fail(t, "raidLogMax", "must be >= 1."); if (t.Raiders == null || t.Raiders.Count == 0) throw Fail(t, "raiders", "a raid with nobody in it can never be played."); if (t.BossSpecies == null) throw Fail(t, "bossSpecies", "the last wave needs a species to build its aggressive variant from."); foreach (var stack in t.Haul ?? new Godot.Collections.Array()) if (stack?.Item == null || stack.Count <= 0) throw Fail(t, "haul", "a haul line has no item or a non-positive count."); } } }