feat(headless): Campaign OP slice OP7 — declared characterOptions with seed-diff sends

Adds an optional, strict `characterOptions` block to the headless bot config (D8): keys are exactly the lane-B tier-1 (22) + tier-2 (4) bot-declarable CharacterOptionId enum-member spellings; an unknown/out-of-tier name fails config load naming the offending key, before it can ever reach the wire. HeadlessCharacterOptionsSeeder diffs declared-vs-actual once both of ACE's real preconditions are known true — GameActionLoginComplete sent (the FirstEnterWorldDone gate SetCharacterOptions 0x01A1 needs) and a real PlayerDescription has seeded RuntimeCharacterOptionsState (HasServerSeed) — learned from whichever of two hooks lands second. Every differing id routes through OP1's shared IRuntimeCharacterCommands seam: auto-save ids send SetSingleOption (0x0005) immediately; batched ids also call SetSingleOption (which only dirties the module) followed by exactly one SaveOptions flush after the whole declared set has been walked. Idempotent on reconnect by construction — no dedupe latch, the diff simply finds nothing once the server agrees. RuntimeLiveEntitySessionController gains a passive onLoginCompleteSent observation hook (additive only, never changes when/whether it sends) so the headless host can learn ACE's gate opened from any of its own two internal send sites; the third site (direct first-entry completion) is already owned by HeadlessSessionHost itself. All wiring is synchronous delegate calls on Runtime's one dedicated update thread — no new async/Task continuation, honoring #368. Tests: schema (valid parse, unknown/tier-3 name rejected naming the key, non-bool rejected, empty/absent no-op), the diff engine against a fake IRuntimeCharacterCommands (nothing-to-send, auto-save-only, batched-with- flush, mixed ordering, reconnect idempotence), and two wiring integration tests — one dispatching a real PlayerDescription game event end-to-end to a captured wire action, one proving the send lands on the same dedicated thread every Tick runs on. Full solution suite: 12,935 passed / 4 skipped / 0 failed (+17 over baseline 12,918/4/0). No register row: the characterOptions bot-config surface is acdream- native tooling over retail's own wire mechanisms (both already ported by OP1), not a retail UI port with a divergence to record. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-08-11 02:45:08 +02:00 · 2026-08-11 02:45:08 +02:00 · 09cb548a32
commit 09cb548a32
parent efe80d5a0d
9 changed files with 1278 additions and 5 deletions
--- a/tests/AcDream.Headless.Tests/HeadlessCharacterOptionsSeederTests.cs
+++ b/tests/AcDream.Headless.Tests/HeadlessCharacterOptionsSeederTests.cs
@ -0,0 +1,289 @@
+using AcDream.Core.Net.Messages;
+using AcDream.Headless.Hosting;
+using AcDream.Runtime;
+using AcDream.Runtime.Gameplay;
+
+namespace AcDream.Headless.Tests;
+
+/// <summary>
+/// Campaign OP slice OP7 (2026-08-11), D8: the declared-vs-actual diff engine
+/// (<see cref="HeadlessCharacterOptionsSeeder"/>) unit-tested against a fake
+/// <see cref="IRuntimeCharacterCommands"/> so these tests never need a live
+/// session, a wire, or a physics/collision fixture — only a bare
+/// <see cref="GameRuntime"/> for its <c>CharacterOwner.Options</c> state and
+/// <c>Generation</c> token. <see cref="RuntimeCharacterOptionsState.Replace"/>
+/// stands in for "a PlayerDescription just landed" exactly like
+/// <c>LiveSessionEventRouter</c>'s own <c>onCharacterOptions</c> wiring does.
+/// </summary>
+public sealed class HeadlessCharacterOptionsSeederTests
+{
+    // AutoRepeatAttack (0x00, Options1 0x00000002) is auto-save — sends
+    // SetSingleOption (0x0005) immediately, per CharacterOptionTable.
+    // IgnoreTradeRequests (0x03, Options1 0x00020000) is batched — dirties
+    // the module; only SaveOptions flushes it. Both are exercised by name
+    // throughout this file's tests.
+    private const uint AutoSaveMask = 0x00000002u;
+
+    [Fact]
+    public void DeclaredEqualsActualSendsNothing()
+    {
+        using GameRuntime runtime = NewRuntime();
+        runtime.CharacterOwner.Options.Replace(0u, 0u);
+        var commands = new FakeCharacterCommands(runtime.CharacterOwner.Options);
+        var seeder = new HeadlessCharacterOptionsSeeder(
+            new Dictionary<CharacterOptionId, bool>
+            {
+                [CharacterOptionId.AutoRepeatAttack] = false,
+            },
+            runtime,
+            commands);
+
+        seeder.NoteLoginCompleteSent();
+        seeder.NoteOptionsSeeded();
+
+        Assert.Empty(commands.CallOrder);
+    }
+
+    [Fact]
+    public void AutoSaveDifferenceSendsExactlyOneSetSingleOption()
+    {
+        using GameRuntime runtime = NewRuntime();
+        runtime.CharacterOwner.Options.Replace(0u, 0u);
+        var commands = new FakeCharacterCommands(runtime.CharacterOwner.Options);
+        var seeder = new HeadlessCharacterOptionsSeeder(
+            new Dictionary<CharacterOptionId, bool>
+            {
+                [CharacterOptionId.AutoRepeatAttack] = true,
+            },
+            runtime,
+            commands);
+
+        seeder.NoteLoginCompleteSent();
+        seeder.NoteOptionsSeeded();
+
+        var call = Assert.Single(commands.SingleOptionCalls);
+        Assert.Equal((uint)CharacterOptionId.AutoRepeatAttack, call.OptionId);
+        Assert.True(call.Value);
+        Assert.Equal(0, commands.SaveOptionsCallCount);
+        Assert.Equal(["set:0"], commands.CallOrder);
+    }
+
+    [Fact]
+    public void BatchedDifferenceSendsSetSingleOptionThenExactlyOneSaveOptionsAtTheEnd()
+    {
+        using GameRuntime runtime = NewRuntime();
+        runtime.CharacterOwner.Options.Replace(0u, 0u);
+        var commands = new FakeCharacterCommands(runtime.CharacterOwner.Options);
+        var seeder = new HeadlessCharacterOptionsSeeder(
+            new Dictionary<CharacterOptionId, bool>
+            {
+                [CharacterOptionId.IgnoreTradeRequests] = true,
+            },
+            runtime,
+            commands);
+
+        seeder.NoteLoginCompleteSent();
+        seeder.NoteOptionsSeeded();
+
+        var call = Assert.Single(commands.SingleOptionCalls);
+        Assert.Equal((uint)CharacterOptionId.IgnoreTradeRequests, call.OptionId);
+        Assert.True(call.Value);
+        Assert.Equal(1, commands.SaveOptionsCallCount);
+        Assert.Equal(["set:3", "save"], commands.CallOrder);
+    }
+
+    [Fact]
+    public void MixedDeclarationOrdersAllSetsBeforeTheSingleFlush()
+    {
+        using GameRuntime runtime = NewRuntime();
+        runtime.CharacterOwner.Options.Replace(0u, 0u);
+        var commands = new FakeCharacterCommands(runtime.CharacterOwner.Options);
+        var seeder = new HeadlessCharacterOptionsSeeder(
+            new Dictionary<CharacterOptionId, bool>
+            {
+                // Declared out of id order on purpose — the seeder sorts
+                // id-ascending internally, so the batched id (0x03) is
+                // expected AFTER the auto-save id (0x00) regardless of
+                // declaration order, with the flush always last.
+                [CharacterOptionId.IgnoreTradeRequests] = true,
+                [CharacterOptionId.AutoRepeatAttack] = true,
+            },
+            runtime,
+            commands);
+
+        seeder.NoteLoginCompleteSent();
+        seeder.NoteOptionsSeeded();
+
+        Assert.Equal(2, commands.SingleOptionCalls.Count);
+        Assert.Equal(1, commands.SaveOptionsCallCount);
+        Assert.Equal(["set:0", "set:3", "save"], commands.CallOrder);
+    }
+
+    [Fact]
+    public void NeitherPreconditionAloneSendsAnything()
+    {
+        using GameRuntime runtime = NewRuntime();
+        var commands = new FakeCharacterCommands(runtime.CharacterOwner.Options);
+        var seeder = new HeadlessCharacterOptionsSeeder(
+            new Dictionary<CharacterOptionId, bool>
+            {
+                [CharacterOptionId.AutoRepeatAttack] = true,
+            },
+            runtime,
+            commands);
+
+        // Login-complete alone: HasServerSeed is still false (no Replace
+        // ever ran), so the diff cannot trust live state yet.
+        seeder.NoteLoginCompleteSent();
+        Assert.Empty(commands.CallOrder);
+
+        // Now the seed lands — both preconditions are satisfied and the
+        // deferred diff runs from THIS call.
+        runtime.CharacterOwner.Options.Replace(0u, 0u);
+        seeder.NoteOptionsSeeded();
+
+        Assert.Single(commands.SingleOptionCalls);
+    }
+
+    [Fact]
+    public void OptionsSeededBeforeLoginCompleteDefersUntilLoginCompleteArrives()
+    {
+        using GameRuntime runtime = NewRuntime();
+        runtime.CharacterOwner.Options.Replace(0u, 0u);
+        var commands = new FakeCharacterCommands(runtime.CharacterOwner.Options);
+        var seeder = new HeadlessCharacterOptionsSeeder(
+            new Dictionary<CharacterOptionId, bool>
+            {
+                [CharacterOptionId.AutoRepeatAttack] = true,
+            },
+            runtime,
+            commands);
+
+        seeder.NoteOptionsSeeded();
+        Assert.Empty(commands.CallOrder);
+
+        seeder.NoteLoginCompleteSent();
+        Assert.Single(commands.SingleOptionCalls);
+    }
+
+    [Fact]
+    public void EmptyDeclarationNeverSendsRegardlessOfBothSignals()
+    {
+        using GameRuntime runtime = NewRuntime();
+        runtime.CharacterOwner.Options.Replace(0xFFFFFFFFu, 0xFFFFFFFFu);
+        var commands = new FakeCharacterCommands(runtime.CharacterOwner.Options);
+        var seeder = new HeadlessCharacterOptionsSeeder(
+            new Dictionary<CharacterOptionId, bool>(),
+            runtime,
+            commands);
+
+        Assert.False(seeder.HasDeclaredOptions);
+        seeder.NoteLoginCompleteSent();
+        seeder.NoteOptionsSeeded();
+
+        Assert.Empty(commands.CallOrder);
+    }
+
+    /// <summary>
+    /// D8 idempotence — the acceptance bar is "by construction", not a
+    /// special-cased dedupe: a fresh, second seeder instance (mirroring the
+    /// fresh instance <c>HeadlessSessionHost.CreateEventRoute</c> constructs
+    /// per reconnect) diffs against the SAME declared dictionary but against
+    /// live state that already reflects what the first seeder sent — the
+    /// second diff simply finds nothing to do.
+    /// </summary>
+    [Fact]
+    public void ReconnectWithSameDeclarationsAgainstServerThatNowAgreesSendsNothing()
+    {
+        using GameRuntime runtime = NewRuntime();
+        var declared = new Dictionary<CharacterOptionId, bool>
+        {
+            [CharacterOptionId.AutoRepeatAttack] = true,
+        };
+
+        // First connect: server has the option OFF; the bot's declared
+        // value differs, so it sends once.
+        runtime.CharacterOwner.Options.Replace(0u, 0u);
+        var firstCommands = new FakeCharacterCommands(runtime.CharacterOwner.Options);
+        var firstSeeder = new HeadlessCharacterOptionsSeeder(
+            declared, runtime, firstCommands);
+        firstSeeder.NoteLoginCompleteSent();
+        firstSeeder.NoteOptionsSeeded();
+        Assert.Single(firstCommands.SingleOptionCalls);
+
+        // Reconnect: a fresh seeder instance (per CreateEventRoute's own
+        // per-route construction), and the server's fresh PlayerDescription
+        // now echoes what the bot itself set last time.
+        runtime.CharacterOwner.Options.ResetSession();
+        runtime.CharacterOwner.Options.Replace(AutoSaveMask, 0u);
+        var secondCommands = new FakeCharacterCommands(runtime.CharacterOwner.Options);
+        var secondSeeder = new HeadlessCharacterOptionsSeeder(
+            declared, runtime, secondCommands);
+        secondSeeder.NoteLoginCompleteSent();
+        secondSeeder.NoteOptionsSeeded();
+
+        Assert.Empty(secondCommands.CallOrder);
+    }
+
+    private static GameRuntime NewRuntime()
+    {
+        var gameplay = new HeadlessGameplayOperations();
+        var runtime = new GameRuntime(new GameRuntimeDependencies(
+            gameplay,
+            gameplay,
+            gameplay,
+            gameplay));
+        gameplay.Bind(runtime, catalog: null, () => "account");
+        return runtime;
+    }
+
+    /// <summary>
+    /// Writes the bit into <paramref name="options"/> as part of
+    /// <see cref="SetSingleOption"/>, mirroring the REAL
+    /// <c>DirectGameRuntimeCommandAdapter.SetSingleOption</c> →
+    /// <c>RuntimeCharacterOptionsState.TrySetOption</c> contract: the local
+    /// copy updates synchronously, in the same call, before the method
+    /// returns. Without this, a fake that only records the call (never
+    /// mutating live state) would make a SECOND diff pass — e.g. a
+    /// legitimate redundant <c>NoteLoginCompleteSent</c>/<c>NoteOptionsSeeded</c>
+    /// pairing — re-find the same already-handled mismatch and re-send it,
+    /// which is a fidelity gap in the fake, not a real defect: production's
+    /// idempotence depends on exactly this synchronous local write.
+    /// </summary>
+    private sealed class FakeCharacterCommands(
+        RuntimeCharacterOptionsState options) : IRuntimeCharacterCommands
+    {
+        internal List<(uint OptionId, bool Value)> SingleOptionCalls { get; } = [];
+        internal int SaveOptionsCallCount { get; private set; }
+        internal List<string> CallOrder { get; } = [];
+
+        public RuntimeCommandResult Advance(
+            RuntimeGenerationToken expectedGeneration,
+            in RuntimeAdvancementCommand command) =>
+            throw new NotSupportedException(
+                "HeadlessCharacterOptionsSeeder never calls Advance.");
+
+        public RuntimeCommandResult SetSingleOption(
+            RuntimeGenerationToken expectedGeneration,
+            uint optionId,
+            bool value)
+        {
+            SingleOptionCalls.Add((optionId, value));
+            CallOrder.Add($"set:{optionId}");
+            options.SetOptionBit(optionId, value);
+            return new RuntimeCommandResult(
+                RuntimeCommandStatus.Accepted,
+                expectedGeneration);
+        }
+
+        public RuntimeCommandResult SaveOptions(
+            RuntimeGenerationToken expectedGeneration)
+        {
+            SaveOptionsCallCount++;
+            CallOrder.Add("save");
+            return new RuntimeCommandResult(
+                RuntimeCommandStatus.Accepted,
+                expectedGeneration);
+        }
+    }
+}