feat(triggers): D2 trigger state machine — gate set, bounded pending cycles, refractory, per-entry deadlines, XmlSpawner migration

.config/dotnet-tools.json

@@ -0,0 +1,12 @@
+{
+  "version": 1,
+  "isRoot": true,
+  "tools": {
+    "modernuoschemagenerator": {
+      "version": "4.1.0",
+      "commands": [
+        "ModernUOSchemaGenerator"
+      ]
+    }
+  }
+}

.gitignore

@@ -3,6 +3,8 @@
 /Projects/*/bin
 /Projects/*/Generated
 /Projects/ModernSpawner.Benchmarks/BenchmarkDotNet.Artifacts/
+# dotnet run --project writes the artifacts under the working directory, not the project.
+/BenchmarkDotNet.Artifacts/
 /TestResults/
 
 # Working notes and generated docs live here uncommitted (same convention as ModernUO)

CLAUDE.md

@@ -26,7 +26,7 @@ pull requests; until a PR merges, the submodule may be pinned to that PR's head
 
 ```sh
 dotnet build ModernSpawner.slnx            # builds ModernUO Server/UOContent from the submodule too
-dotnet test Projects/ModernSpawner.Tests   # 427 tests; the lifecycle collection boots a ModernUO test server
+dotnet test Projects/ModernSpawner.Tests   # 587 tests; the lifecycle collection boots a ModernUO test server
 dotnet build -c Analyze                    # analyzers + Rules.ruleset
 ```
 
@@ -36,7 +36,9 @@ dotnet build -c Analyze                    # analyzers + Rules.ruleset
 World-backed tests (`Projects/ModernSpawner.Tests/Core/ModernSpawnerLifecycleTests.cs`) share a
 process-wide ModernUO bootstrap in `Projects/ModernSpawner.Tests/Fixtures/ModernSpawnerTestServer.cs`
 and run in a `DisableParallelization` xunit collection; use that fixture for any new test that needs a
-live spawner rather than standing up World/Core state by hand.
+live spawner rather than standing up World/Core state by hand. The 12k-spawner trigger perf harness
+(`Projects/ModernSpawner.Tests/Perf/TriggerPerfHarness.cs`) is part of that count but is a no-op unless
+`MODERNSPAWNER_PERF=1` is set, so the default run stays sub-second.
 
 ## Rules
 
@@ -60,14 +62,24 @@ ModernSpawner-specific:
   base contract (`Entries`, `EntrySpan`, `CreateEntry`, `AddEntryCore`, …) runs over it and the lifecycle
   hooks (`OnStarted`, `OnSpawned`, `OnSpawnedDeath`, entry-aware `GetSpawnPosition`) carry the modern
   behaviour. Never add a parallel entry list or hide base members with `new`.
-- Triggers register through `TriggerSystem`; proximity uses `Item.HandlesOnMovement`/`OnMovement`, speech
-  uses `HandlesOnSpeech`, skill uses `Server.Misc.SkillEvents.SkillUsed` (players only). Extended (beyond
-  24-tile) proximity is stubbed pending a ModernUO area-movement API.
-- Trigger list changes go through the generated helpers (`AddToTriggerDefinitions`,
-  `RemoveFromTriggerDefinitionsAt`, `ClearTriggerDefinitions`), then call `EnsureTriggersActive()`; the
-  `TriggerActivated` setter does this for you. Never call `TriggerSystem.ActivateTriggers` directly — it is
-  not idempotent, and within `Projects/ModernSpawner` `EnsureTriggersActive` is its only caller (tests call
-  it deliberately, to build the stale registrations teardown has to survive).
+- Triggers are a state machine, not a bool: dispatch (`OnMovement`/`OnSpeech`/kill/skill) never spawns —
+  a match calls `spawner.RequestCycle(trigger, in context)`, which only mutates spawner state (cooldown,
+  refractory, the pending-cycle queue) and asks `TriggerSystem` for a drain; the outermost dispatch runs
+  the cycle once it returns. All of that state (the gate set, the queue, cooldowns, kill counts, per-entry
+  deadlines) lives on the spawner, so a tick never looks anything up. See `dev-docs/architecture.md` §5 for
+  the tick-precedence and event transition table.
+- Trigger definitions are `TriggerDefinition { Id, Text }` with a stable id generated once; mutate the list
+  only through `AddTriggerDefinition`/`RemoveTriggerDefinitionAt`/`ClearTriggerDefinitions` — they assign
+  the id and call `EnsureTriggersActive()` for you. Never call `TriggerSystem.ActivateTriggers` directly:
+  it is not idempotent on its own, and within `Projects/ModernSpawner`, `ModernSpawner.EnsureTriggersActive`
+  is its only caller (tests call it deliberately, to build the stale-registration cases teardown has to
+  survive). Registration follows `TriggerActivated` and the definition list, never `Running` — `Start()`/
+  `Stop()` only arm or disarm the timer.
+- Proximity uses `Item.HandlesOnMovement`/`OnMovement`, speech uses `HandlesOnSpeech`, skill uses
+  `Server.Misc.SkillEvents.SkillUsed` (players only). Extended (beyond 24-tile) proximity is clamped to
+  `Core.GlobalMaxUpdateRange` with a warning.
+- Per-event-trigger tokens (`wake:`, `mode:`, `when:`) are a suffix, recognised only after a grammar's full
+  positional list — never write one where a positional field could be misread as a token name.
 
 ## ModernUO changes
 

Projects/ModernSpawner.Benchmarks/Program.cs

@@ -22,14 +22,17 @@ dotnet run -c Release [options]
           --compile     Run compilation cost benchmarks
           --set         Run property set benchmarks
           --expr        Run XmlSpawner vs ModernSpawner expression comparison
+          --triggers    Run the D2 trigger dispatch benchmarks (set lookup, request/drain)
           --quick       Run with fewer iterations (for quick testing)
+          --filter <p>  Hand the arguments to BenchmarkDotNet's own switcher, e.g. --filter *TriggerDispatch*
           --help, -h    Show this help
 
         Examples:
           dotnet run -c Release --all
           dotnet run -c Release --expr
           dotnet run -c Release --spawner --condition
           dotnet run -c Release --quick --simple
+          dotnet run -c Release -- --filter *TriggerDispatch*
         """);
     return;
 }
@@ -44,6 +47,14 @@ dotnet run -c Release --quick --simple
     config = config.WithOptions(ConfigOptions.DisableOptimizationsValidator);
 }
 
+// A --filter run is handed straight to BenchmarkDotNet's switcher, which understands globs over the
+// whole assembly. The curated flags below stay for the suites that predate it.
+if (args.Contains("--filter"))
+{
+    BenchmarkSwitcher.FromAssembly(typeof(TriggerDispatchLookupBenchmarks).Assembly).Run(args, config);
+    return;
+}
+
 // Determine which benchmarks to run
 var runAll = args.Contains("--all") || args.Length == 0;
 var benchmarkTypes = new List<Type>();
@@ -80,6 +91,12 @@ dotnet run -c Release --quick --simple
     benchmarkTypes.Add(typeof(ComplexExpressionBenchmarks));
 }
 
+if (runAll || args.Contains("--triggers"))
+{
+    benchmarkTypes.Add(typeof(TriggerDispatchLookupBenchmarks));
+    benchmarkTypes.Add(typeof(TriggerDispatchRequestDrainBenchmarks));
+}
+
 if (benchmarkTypes.Count == 0)
 {
     Console.WriteLine("No benchmarks selected. Use --help for options.");