erik/acdream
1
0
Fork 0
Code Issues Pull requests Projects Releases 6 Packages Wiki Activity Actions

feat(plugins): MossTank — a self-buffing plugin, and the automation surface it needed

Browse source 
First consumer of acdream's plugin automation surface, and the first slice of
the VTank-class plugin milestone
(docs/research/2026-07-29-vtank-plugin-automation-requirements.md).

MossTank shows a panel with a Buff button; clicking it casts every self-buff
the character is missing, skips what is already in force at an equal or higher
tier, and refreshes what is nearly expired.

The host/plugin line is the load-bearing decision here. The host publishes
spell DATA -- family, tier, difficulty, mana, duration -- plus a cast
primitive with a preflight gate. The plugin owns the POLICY. That is the
architectural conclusion the requirements research reached: VTank's engine
lived in plugin-land, built on Decal's primitives, and baking "best buff for
skill X" into the host would start pulling the engine inward one convenience
at a time.

Why the plan is driven off the spellbook rather than off trained skills, which
is the obvious reading of "buff every trained and specialised skill": the
client cannot honestly make that mapping. The link between a spell and the
stat it modifies arrives from the SERVER in the enchantment message and is
absent from the client's own spell table. What the client does know is which
spells the character has learned -- and a character only learns buffs for the
skills they use, so the spellbook reaches the same set without inventing a
mapping the client has no grounds for.

Surface added, all BCL-only so Plugin.Abstractions keeps its zero project
references:

* ICharacterInfo, ISpellCatalog, IMagicCommands, grouped behind one
  IAutomationSurface so IPluginHost grows by one member rather than three.
* IEvents.Tick. Automation is sequences, not single calls -- a buff pass casts
  several spells and must wait between them. Without a host tick a plugin
  would need its own timer thread re-entering the host off its update thread.
* NoOpAutomationSurface for hosts with no live session, so a plugin keeps one
  code path and checks IsAvailable.

Markup gained <button> and <label>; it previously supported only <meter>, with
a comment promising the rest. Buttons bind onclick to an Action property and
FAIL THE PANEL LOAD if it does not resolve -- a silently dead button is worse
than a panel that refuses to load, because the user clicks and there is
nothing to diagnose. Labels bind through a Func so a status line tracks its
binding instead of freezing at build time.

Enchantment reads use EnchantmentsInEffectSnapshot rather than the raw active
set: retail leaves a weaker same-family enchantment in the registry while a
stronger one is in force, and a plugin asking "am I buffed?" means in force.

BuffPlan is a pure function of (known buffs, active enchantments) precisely so
it can be tested without a session; 9 tests cover tier supersede, the
family-0 no-stack bucket that must not be de-duplicated, expiry refresh, and
plan stability across the rebuilds the tick loop performs.

Solution builds clean; 14,421 tests pass on the standard hermetic lane filter,
0 failures.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Erik 2026-08-20 16:22:28 +02:00
parent 690f21889e
commit 9d1117b923
27 changed files with 1546 additions and 10 deletions
Download patch file Download diff file Expand all files Collapse all files

12
tests/AcDream.App.Tests/Plugins/GraphicalPluginSessionTests.cs
View file

@ -30,7 +30,8 @@ public sealed class GraphicalPluginSessionTests
var events = new WorldEvents();
var selection = new SelectionState();
var ui = new BufferedUiRegistry();
var host = new AppPluginHost(logger, state, events, selection, ui);
var host = new AppPluginHost(logger, state, events, selection, ui,
NoOpAutomationSurface.Instance);
using GraphicalPluginSession plugins = GraphicalPluginSession.Create(
paths,
@ -85,7 +86,8 @@ public sealed class GraphicalPluginSessionTests
new WorldGameState(),
new WorldEvents(),
new SelectionState(),
ui);
ui,
NoOpAutomationSurface.Instance);
using GraphicalPluginSession plugins = GraphicalPluginSession.Create(
paths,
@ -123,7 +125,8 @@ public sealed class GraphicalPluginSessionTests
new WorldGameState(),
events,
selection,
ui);
ui,
NoOpAutomationSurface.Instance);
using GraphicalPluginSession plugins = GraphicalPluginSession.Create(
paths,
@ -176,7 +179,8 @@ public sealed class GraphicalPluginSessionTests
new WorldGameState(),
events,
selection,
ui);
ui,
NoOpAutomationSurface.Instance);
using GraphicalPluginSession plugins = GraphicalPluginSession.Create(
paths,

73
tests/AcDream.App.Tests/UI/MarkupDocumentTests.cs
View file

@ -75,4 +75,77 @@ public class MarkupDocumentTests
Assert.Equal(0x06001133u, meter.FrontRight);
Assert.NotNull(meter.SpriteResolve);
}
private sealed class ButtonBinding
{
public int Clicks { get; private set; }
public string Status { get; set; } = "idle";
public Action Go => () => Clicks++;
public Action? Missing => null;
}
[Fact]
public void Build_ButtonInvokesTheBoundActionOnClick()
{
const string xml =
"<panel x=\"0\" y=\"0\" w=\"100\" h=\"60\">" +
" <button x=\"4\" y=\"8\" w=\"60\" h=\"20\" text=\"Buff\" onclick=\"{Go}\"/>" +
"</panel>";
var binding = new ButtonBinding();
var panel = MarkupDocument.Build(xml, binding, _ => ((uint)1, 32, 32));
var button = Assert.IsType<UiSimpleButton>(panel.Children[0]);
Assert.Equal("Buff", button.Text);
Assert.Equal(60f, button.Width);
button.OnEvent(new UiEvent { Type = UiEventType.Click });
button.OnEvent(new UiEvent { Type = UiEventType.Click });
Assert.Equal(2, binding.Clicks);
}
[Fact]
public void Build_ButtonWithUnresolvableHandlerFailsLoudly()
{
// A silently dead button is worse than a panel that refuses to load:
// the user clicks and nothing happens, with nothing to diagnose.
const string xml =
"<panel x=\"0\" y=\"0\" w=\"100\" h=\"60\">" +
" <button x=\"0\" y=\"0\" w=\"10\" h=\"10\" text=\"X\" onclick=\"{NoSuchProperty}\"/>" +
"</panel>";
Assert.Throws<FormatException>(
() => MarkupDocument.Build(xml, new ButtonBinding(), _ => ((uint)1, 32, 32)));
}
[Fact]
public void Build_BoundLabelTracksTheBindingRatherThanFreezing()
{
const string xml =
"<panel x=\"0\" y=\"0\" w=\"100\" h=\"60\">" +
" <label x=\"2\" y=\"4\" text=\"{Status}\"/>" +
"</panel>";
var binding = new ButtonBinding();
var panel = MarkupDocument.Build(xml, binding, _ => ((uint)1, 32, 32));
var label = Assert.IsType<UiLabel>(panel.Children[0]);
Assert.Equal("idle", label.TextSource!());
binding.Status = "casting";
Assert.Equal("casting", label.TextSource!());
}
[Fact]
public void Build_LiteralLabelTextIsUsedVerbatim()
{
const string xml =
"<panel x=\"0\" y=\"0\" w=\"100\" h=\"60\">" +
" <label x=\"0\" y=\"0\" text=\"MossTank\"/>" +
"</panel>";
var panel = MarkupDocument.Build(xml, new ButtonBinding(), _ => ((uint)1, 32, 32));
var label = Assert.IsType<UiLabel>(panel.Children[0]);
Assert.Equal("MossTank", label.TextSource!());
}
}

7
tests/AcDream.Core.Tests/Plugins/PluginLoaderTests.cs
View file

@ -34,6 +34,7 @@ public class PluginLoaderTests
public IEvents Events { get; } = new StubEvents();
public ISelectionService Selection { get; } = new SelectionState();
public IUiRegistry Ui { get; } = new StubUiRegistry();
public IAutomationSurface Automation => NoOpAutomationSurface.Instance;
}
private sealed class StubUiRegistry : IUiRegistry
@ -60,6 +61,12 @@ public class PluginLoaderTests
add { }
remove { }
}
public event Action<double> Tick
{
add { }
remove { }
}
}
[Fact]

7
tests/AcDream.Core.Tests/Plugins/PluginSessionTests.cs
View file

@ -157,6 +157,7 @@ public sealed class PluginSessionTests
public IEvents Events { get; } = new StubEvents();
public ISelectionService Selection { get; } = new SelectionState();
public IUiRegistry Ui => NoOpUiRegistry.Instance;
public IAutomationSurface Automation => NoOpAutomationSurface.Instance;
}
private sealed class StubLogger : IPluginLogger
@ -178,6 +179,12 @@ public sealed class PluginSessionTests
add { }
remove { }
}
public event Action<double> Tick
{
add { }
remove { }
}
}
private sealed class TemporaryDirectory : IDisposable

22
tests/AcDream.Plugins.MossTank.Tests/AcDream.Plugins.MossTank.Tests.csproj Normal file
View file

@ -0,0 +1,22 @@
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>net10.0</TargetFramework>
<ImplicitUsings>enable</ImplicitUsings>
<Nullable>enable</Nullable>
<IsPackable>false</IsPackable>
<LangVersion>latest</LangVersion>
<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="coverlet.collector" />
<PackageReference Include="Microsoft.NET.Test.Sdk" />
<PackageReference Include="xunit" />
<PackageReference Include="xunit.runner.visualstudio" />
</ItemGroup>
<ItemGroup>
<Using Include="Xunit" />
</ItemGroup>
<ItemGroup>
<ProjectReference Include="..\..\src\AcDream.Plugins.MossTank\AcDream.Plugins.MossTank.csproj" />
</ItemGroup>
</Project>

150
tests/AcDream.Plugins.MossTank.Tests/BuffPlanTests.cs Normal file
View file

@ -0,0 +1,150 @@
using AcDream.Plugin.Abstractions;
using AcDream.Plugins.MossTank;
namespace AcDream.Plugins.MossTank.Tests;
/// <summary>
/// The buff policy is the part of MossTank that decides what gets cast, so it
/// is the part worth pinning. It is a pure function of (known buffs, active
/// enchantments) precisely so these tests need no host and no session.
/// </summary>
public class BuffPlanTests
{
private const double Refresh = 60.0;
private static PluginSpellInfo Spell(
uint id, uint family, int tier, int mana = 10) =>
new(id, $"spell-{id}", family, tier, Difficulty: 100, ManaCost: mana,
DurationSeconds: 1800f, IsSelfTargeted: true, IsBeneficial: true);
private static PluginActiveEnchantment Active(
uint id, uint family, int tier, double seconds) =>
new(id, family, tier, seconds);
[Fact]
public void WithNothingActive_CastsTheStrongestTierPerFamily()
{
var known = new[]
{
Spell(1, family: 10, tier: 1),
Spell(2, family: 10, tier: 7),
Spell(3, family: 20, tier: 4),
};
var plan = BuffPlan.Build(known, Array.Empty<PluginActiveEnchantment>(), Refresh);
Assert.Equal(2, plan.Count);
Assert.Contains(plan, s => s.SpellId == 2); // tier 7 beat tier 1
Assert.Contains(plan, s => s.SpellId == 3);
Assert.DoesNotContain(plan, s => s.SpellId == 1);
}
[Fact]
public void SkipsFamiliesAlreadyInForceAtTheSameTier()
{
var known = new[] { Spell(2, family: 10, tier: 7) };
var active = new[] { Active(2, family: 10, tier: 7, seconds: 900) };
Assert.Empty(BuffPlan.Build(known, active, Refresh));
}
[Fact]
public void RecastsWhenAStrongerTierIsKnownThanTheOneInForce()
{
// The whole point of tracking tier rather than mere presence: a
// level-1 buff in force must not block casting the level-7 one.
var known = new[] { Spell(2, family: 10, tier: 7) };
var active = new[] { Active(1, family: 10, tier: 1, seconds: 900) };
var plan = BuffPlan.Build(known, active, Refresh);
Assert.Single(plan);
Assert.Equal(2u, plan[0].SpellId);
}
[Fact]
public void RefreshesABuffThatIsAboutToExpire()
{
var known = new[] { Spell(2, family: 10, tier: 7) };
var active = new[] { Active(2, family: 10, tier: 7, seconds: 5) };
var plan = BuffPlan.Build(known, active, Refresh);
Assert.Single(plan);
Assert.Equal(2u, plan[0].SpellId);
}
[Fact]
public void TreatsFamilyZeroSpellsIndividually()
{
// Family 0 is retail's "does not stack" bucket. Collapsing it by family
// would silently drop every such buff but one, and they are unrelated
// spells that all need casting.
var known = new[]
{
Spell(101, family: 0, tier: 1),
Spell(102, family: 0, tier: 1),
Spell(103, family: 0, tier: 1),
};
var plan = BuffPlan.Build(known, Array.Empty<PluginActiveEnchantment>(), Refresh);
Assert.Equal(3, plan.Count);
}
[Fact]
public void SkipsAnIndividuallyActiveFamilyZeroSpell()
{
var known = new[] { Spell(101, family: 0, tier: 1), Spell(102, family: 0, tier: 1) };
var active = new[] { Active(101, family: 0, tier: 1, seconds: 900) };
var plan = BuffPlan.Build(known, active, Refresh);
Assert.Single(plan);
Assert.Equal(102u, plan[0].SpellId);
}
[Fact]
public void OrdersCheapestFirstSoAPartialPassLandsMoreBuffs()
{
var known = new[]
{
Spell(1, family: 10, tier: 1, mana: 500),
Spell(2, family: 20, tier: 1, mana: 5),
Spell(3, family: 30, tier: 1, mana: 50),
};
var plan = BuffPlan.Build(known, Array.Empty<PluginActiveEnchantment>(), Refresh);
Assert.Equal(new uint[] { 2, 3, 1 }, plan.Select(s => s.SpellId).ToArray());
}
[Fact]
public void IsStableAcrossRepeatedBuilds()
{
// The tick loop rebuilds the plan every pass; an unstable order would
// make it re-cast the same spell while starving another.
var known = new[]
{
Spell(1, family: 10, tier: 1, mana: 20),
Spell(2, family: 20, tier: 1, mana: 20),
Spell(3, family: 30, tier: 1, mana: 20),
};
var first = BuffPlan.Build(known, Array.Empty<PluginActiveEnchantment>(), Refresh);
var second = BuffPlan.Build(known, Array.Empty<PluginActiveEnchantment>(), Refresh);
Assert.Equal(
first.Select(s => s.SpellId).ToArray(),
second.Select(s => s.SpellId).ToArray());
}
[Fact]
public void EmptySpellbookProducesNoPlan()
{
Assert.Empty(BuffPlan.Build(
Array.Empty<PluginSpellInfo>(),
Array.Empty<PluginActiveEnchantment>(),
Refresh));
}
}

113
tests/AcDream.Plugins.MossTank.Tests/packages.neutral.lock.json Normal file
View file

@ -0,0 +1,113 @@
{
"version": 2,
"dependencies": {
"net10.0": {
"coverlet.collector": {
"type": "Direct",
"requested": "[6.0.4, )",
"resolved": "6.0.4",
"contentHash": "lkhqpF8Pu2Y7IiN7OntbsTtdbpR1syMsm2F3IgX6ootA4ffRqWL5jF7XipHuZQTdVuWG/gVAAcf8mjk8Tz0xPg=="
},
"Microsoft.NET.Test.Sdk": {
"type": "Direct",
"requested": "[17.14.1, )",
"resolved": "17.14.1",
"contentHash": "HJKqKOE+vshXra2aEHpi2TlxYX7Z9VFYkr+E5rwEvHC8eIXiyO+K9kNm8vmNom3e2rA56WqxU+/N9NJlLGXsJQ==",
"dependencies": {
"Microsoft.CodeCoverage": "17.14.1",
"Microsoft.TestPlatform.TestHost": "17.14.1"
}
},
"xunit": {
"type": "Direct",
"requested": "[2.9.3, )",
"resolved": "2.9.3",
"contentHash": "TlXQBinK35LpOPKHAqbLY4xlEen9TBafjs0V5KnA4wZsoQLQJiirCR4CbIXvOH8NzkW4YeJKP5P/Bnrodm0h9Q==",
"dependencies": {
"xunit.analyzers": "1.18.0",
"xunit.assert": "2.9.3",
"xunit.core": "[2.9.3]"
}
},
"xunit.runner.visualstudio": {
"type": "Direct",
"requested": "[3.1.4, )",
"resolved": "3.1.4",
"contentHash": "5mj99LvCqrq3CNi06xYdyIAXOEh+5b33F2nErCzI5zWiDdLHXiPXEWFSUAF8zlIv0ZWqjZNCwHTQeAPYbF3pCg=="
},
"Microsoft.CodeCoverage": {
"type": "Transitive",
"resolved": "17.14.1",
"contentHash": "pmTrhfFIoplzFVbhVwUquT+77CbGH+h4/3mBpdmIlYtBi9nAB+kKI6dN3A/nV4DFi3wLLx/BlHIPK+MkbQ6Tpg=="
},
"Microsoft.TestPlatform.ObjectModel": {
"type": "Transitive",
"resolved": "17.14.1",
"contentHash": "xTP1W6Mi6SWmuxd3a+jj9G9UoC850WGwZUps1Wah9r1ZxgXhdJfj1QqDLJkFjHDCvN42qDL2Ps5KjQYWUU0zcQ=="
},
"Microsoft.TestPlatform.TestHost": {
"type": "Transitive",
"resolved": "17.14.1",
"contentHash": "d78LPzGKkJwsJXAQwsbJJ7LE7D1wB+rAyhHHAaODF+RDSQ0NgMjDFkSA1Djw18VrxO76GlKAjRUhl+H8NL8Z+Q==",
"dependencies": {
"Microsoft.TestPlatform.ObjectModel": "17.14.1",
"Newtonsoft.Json": "13.0.3"
}
},
"Newtonsoft.Json": {
"type": "Transitive",
"resolved": "13.0.3",
"contentHash": "HrC5BXdl00IP9zeV+0Z848QWPAoCr9P3bDEZguI+gkLcBKAOxix/tLEAAHC+UvDNPv4a2d18lOReHMOagPa+zQ=="
},
"xunit.abstractions": {
"type": "Transitive",
"resolved": "2.0.3",
"contentHash": "pot1I4YOxlWjIb5jmwvvQNbTrZ3lJQ+jUGkGjWE3hEFM0l5gOnBWS+H3qsex68s5cO52g+44vpGzhAt+42vwKg=="
},
"xunit.analyzers": {
"type": "Transitive",
"resolved": "1.18.0",
"contentHash": "OtFMHN8yqIcYP9wcVIgJrq01AfTxijjAqVDy/WeQVSyrDC1RzBWeQPztL49DN2syXRah8TYnfvk035s7L95EZQ=="
},
"xunit.assert": {
"type": "Transitive",
"resolved": "2.9.3",
"contentHash": "/Kq28fCE7MjOV42YLVRAJzRF0WmEqsmflm0cfpMjGtzQ2lR5mYVj1/i0Y8uDAOLczkL3/jArrwehfMD0YogMAA=="
},
"xunit.core": {
"type": "Transitive",
"resolved": "2.9.3",
"contentHash": "BiAEvqGvyme19wE0wTKdADH+NloYqikiU0mcnmiNyXaF9HyHmE6sr/3DC5vnBkgsWaE6yPyWszKSPSApWdRVeQ==",
"dependencies": {
"xunit.extensibility.core": "[2.9.3]",
"xunit.extensibility.execution": "[2.9.3]"
}
},
"xunit.extensibility.core": {
"type": "Transitive",
"resolved": "2.9.3",
"contentHash": "kf3si0YTn2a8J8eZNb+zFpwfoyvIrQ7ivNk5ZYA5yuYk1bEtMe4DxJ2CF/qsRgmEnDr7MnW1mxylBaHTZ4qErA==",
"dependencies": {
"xunit.abstractions": "2.0.3"
}
},
"xunit.extensibility.execution": {
"type": "Transitive",
"resolved": "2.9.3",
"contentHash": "yMb6vMESlSrE3Wfj7V6cjQ3S4TXdXpRqYeNEI3zsX31uTsGMJjEw6oD5F5u1cHnMptjhEECnmZSsPxB6ChZHDQ==",
"dependencies": {
"xunit.extensibility.core": "[2.9.3]"
}
},
"acdream.plugin.abstractions": {
"type": "Project"
},
"acdream.plugins.mosstank": {
"type": "Project",
"dependencies": {
"AcDream.Plugin.Abstractions": "[1.0.0, )"
}
}
}
}
}