feat(plugins): MossTank — a self-buffing plugin, and the automation surface it needed
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
parent
690f21889e
commit
9d1117b923
27 changed files with 1546 additions and 10 deletions
275
src/AcDream.App/Plugins/AppAutomationSurface.cs
Normal file
275
src/AcDream.App/Plugins/AppAutomationSurface.cs
Normal file
|
|
@ -0,0 +1,275 @@
|
|||
using AcDream.Core.Player;
|
||||
using AcDream.Core.Spells;
|
||||
using AcDream.Plugin.Abstractions;
|
||||
using AcDream.Runtime.Gameplay;
|
||||
|
||||
namespace AcDream.App.Plugins;
|
||||
|
||||
/// <summary>
|
||||
/// Projects the canonical Runtime gameplay owners into the BCL-only plugin
|
||||
/// automation surface.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// Owns nothing: the character state and cast state are borrowed from
|
||||
/// <c>GameRuntime</c> and rebound per session, matching how every other
|
||||
/// graphical projection treats Runtime owners. Between sessions the surface
|
||||
/// reports <see cref="IsAvailable"/> false and every command refuses, rather
|
||||
/// than throwing at a plugin that ticked one frame late.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// The two snapshot lists are rebuilt on Spellbook change notifications rather
|
||||
/// than per read, because a plugin ticking each frame would otherwise force a
|
||||
/// full spellbook walk 60 times a second for data that changes rarely.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
internal sealed class AppAutomationSurface
|
||||
: IAutomationSurface, ICharacterInfo, ISpellCatalog, IMagicCommands, IDisposable
|
||||
{
|
||||
private readonly object _gate = new();
|
||||
|
||||
private RuntimeCharacterState? _character;
|
||||
private RuntimeSpellCastState? _cast;
|
||||
private Spellbook? _spellbook;
|
||||
private bool _disposed;
|
||||
|
||||
private IReadOnlyList<PluginSpellInfo> _knownSelfBuffs = Array.Empty<PluginSpellInfo>();
|
||||
private IReadOnlyList<PluginActiveEnchantment> _enchantments =
|
||||
Array.Empty<PluginActiveEnchantment>();
|
||||
|
||||
public bool IsAvailable
|
||||
{
|
||||
get
|
||||
{
|
||||
lock (_gate)
|
||||
return !_disposed && _character is not null && _cast is not null;
|
||||
}
|
||||
}
|
||||
|
||||
public ICharacterInfo Character => this;
|
||||
public ISpellCatalog Spells => this;
|
||||
public IMagicCommands Magic => this;
|
||||
|
||||
/// <summary>Bind the surface to a live session's owners.</summary>
|
||||
public void Bind(RuntimeCharacterState character, RuntimeSpellCastState cast)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(character);
|
||||
ArgumentNullException.ThrowIfNull(cast);
|
||||
|
||||
Spellbook spellbook = character.Spellbook;
|
||||
lock (_gate)
|
||||
{
|
||||
if (_disposed)
|
||||
return;
|
||||
DetachLocked();
|
||||
_character = character;
|
||||
_cast = cast;
|
||||
_spellbook = spellbook;
|
||||
spellbook.SpellbookChanged += OnSpellbookChanged;
|
||||
spellbook.EnchantmentsChanged += OnEnchantmentsChanged;
|
||||
}
|
||||
|
||||
RebuildSpellbook();
|
||||
RebuildEnchantments();
|
||||
}
|
||||
|
||||
/// <summary>Release the session's owners; reads go inert until the next bind.</summary>
|
||||
public void Unbind()
|
||||
{
|
||||
lock (_gate)
|
||||
DetachLocked();
|
||||
_knownSelfBuffs = Array.Empty<PluginSpellInfo>();
|
||||
_enchantments = Array.Empty<PluginActiveEnchantment>();
|
||||
}
|
||||
|
||||
private void DetachLocked()
|
||||
{
|
||||
if (_spellbook is not null)
|
||||
{
|
||||
_spellbook.SpellbookChanged -= OnSpellbookChanged;
|
||||
_spellbook.EnchantmentsChanged -= OnEnchantmentsChanged;
|
||||
}
|
||||
_spellbook = null;
|
||||
_character = null;
|
||||
_cast = null;
|
||||
}
|
||||
|
||||
private void OnSpellbookChanged() => RebuildSpellbook();
|
||||
|
||||
private void OnEnchantmentsChanged() => RebuildEnchantments();
|
||||
|
||||
private void RebuildSpellbook()
|
||||
{
|
||||
Spellbook? spellbook;
|
||||
lock (_gate)
|
||||
spellbook = _spellbook;
|
||||
if (spellbook is null)
|
||||
{
|
||||
_knownSelfBuffs = Array.Empty<PluginSpellInfo>();
|
||||
return;
|
||||
}
|
||||
|
||||
var built = new List<PluginSpellInfo>();
|
||||
foreach (uint spellId in spellbook.LearnedSpells)
|
||||
{
|
||||
if (!spellbook.TryGetMetadata(spellId, out SpellMetadata meta))
|
||||
continue;
|
||||
if (!meta.IsSelfTargeted || !meta.IsBeneficial || meta.IsDebuff)
|
||||
continue;
|
||||
built.Add(Project(meta));
|
||||
}
|
||||
|
||||
// Stable order so a plugin's buff sequence does not reshuffle between
|
||||
// passes: family first, then strongest tier within it.
|
||||
built.Sort(static (a, b) =>
|
||||
a.Family != b.Family
|
||||
? a.Family.CompareTo(b.Family)
|
||||
: b.Tier.CompareTo(a.Tier));
|
||||
_knownSelfBuffs = built;
|
||||
}
|
||||
|
||||
private void RebuildEnchantments()
|
||||
{
|
||||
Spellbook? spellbook;
|
||||
lock (_gate)
|
||||
spellbook = _spellbook;
|
||||
if (spellbook is null)
|
||||
{
|
||||
_enchantments = Array.Empty<PluginActiveEnchantment>();
|
||||
return;
|
||||
}
|
||||
|
||||
// EnchantmentsInEffectSnapshot, not the raw active set: retail lets a
|
||||
// weaker same-family enchantment sit in the registry while a stronger
|
||||
// one is in force. A plugin asking "am I buffed?" means in force.
|
||||
IReadOnlyList<ActiveEnchantmentRecord> active =
|
||||
spellbook.EnchantmentsInEffectSnapshot;
|
||||
var built = new List<PluginActiveEnchantment>(active.Count);
|
||||
foreach (ActiveEnchantmentRecord record in active)
|
||||
{
|
||||
uint family = 0;
|
||||
int tier = 0;
|
||||
if (spellbook.TryGetMetadata(record.SpellId, out SpellMetadata meta))
|
||||
{
|
||||
family = meta.Family;
|
||||
tier = meta.Generation;
|
||||
}
|
||||
built.Add(new PluginActiveEnchantment(
|
||||
record.SpellId, family, tier, record.Duration));
|
||||
}
|
||||
_enchantments = built;
|
||||
}
|
||||
|
||||
private static PluginSpellInfo Project(SpellMetadata meta) => new(
|
||||
meta.SpellId,
|
||||
meta.Name,
|
||||
meta.Family,
|
||||
meta.Generation,
|
||||
meta.Difficulty,
|
||||
meta.ManaCost,
|
||||
meta.Duration,
|
||||
meta.IsSelfTargeted,
|
||||
meta.IsBeneficial);
|
||||
|
||||
// ── ICharacterInfo ────────────────────────────────────────────────────
|
||||
public bool IsInWorld => IsAvailable;
|
||||
|
||||
public uint CurrentMana => Vital(out uint current, out _) ? current : 0u;
|
||||
|
||||
public uint MaxMana => Vital(out _, out uint maximum) ? maximum : 0u;
|
||||
|
||||
private bool Vital(out uint current, out uint maximum)
|
||||
{
|
||||
current = 0;
|
||||
maximum = 0;
|
||||
RuntimeCharacterState? character;
|
||||
lock (_gate)
|
||||
character = _character;
|
||||
if (character is null)
|
||||
return false;
|
||||
if (!character.View.TryGetVital(
|
||||
(int)LocalPlayerState.VitalKind.Mana, out var vital))
|
||||
{
|
||||
return false;
|
||||
}
|
||||
current = vital.Current;
|
||||
maximum = vital.Maximum;
|
||||
return true;
|
||||
}
|
||||
|
||||
public IReadOnlyList<PluginActiveEnchantment> ActiveEnchantments => _enchantments;
|
||||
|
||||
// ── ISpellCatalog ─────────────────────────────────────────────────────
|
||||
public IReadOnlyList<PluginSpellInfo> KnownSelfBuffs => _knownSelfBuffs;
|
||||
|
||||
public bool TryGet(uint spellId, out PluginSpellInfo info)
|
||||
{
|
||||
Spellbook? spellbook;
|
||||
lock (_gate)
|
||||
spellbook = _spellbook;
|
||||
if (spellbook is not null
|
||||
&& spellbook.TryGetMetadata(spellId, out SpellMetadata meta))
|
||||
{
|
||||
info = Project(meta);
|
||||
return true;
|
||||
}
|
||||
info = default;
|
||||
return false;
|
||||
}
|
||||
|
||||
// ── IMagicCommands ────────────────────────────────────────────────────
|
||||
public bool IsCasting
|
||||
{
|
||||
get
|
||||
{
|
||||
RuntimeSpellCastState? cast;
|
||||
lock (_gate)
|
||||
cast = _cast;
|
||||
return cast?.LastRequestedSpellId is not null;
|
||||
}
|
||||
}
|
||||
|
||||
public PluginCastGate EvaluateGate(uint spellId)
|
||||
{
|
||||
RuntimeSpellCastState? cast;
|
||||
Spellbook? spellbook;
|
||||
lock (_gate)
|
||||
{
|
||||
cast = _cast;
|
||||
spellbook = _spellbook;
|
||||
}
|
||||
if (cast is null || spellbook is null)
|
||||
return PluginCastGate.Unavailable;
|
||||
if (!spellbook.Knows(spellId))
|
||||
return PluginCastGate.NotKnown;
|
||||
|
||||
return cast.EvaluateCastGate(spellId) switch
|
||||
{
|
||||
SpellCastGate.Unknown => PluginCastGate.NotKnown,
|
||||
SpellCastGate.NoTargetNeeded => PluginCastGate.Ready,
|
||||
SpellCastGate.TargetCompatible => PluginCastGate.Ready,
|
||||
_ => PluginCastGate.Refused,
|
||||
};
|
||||
}
|
||||
|
||||
public bool Cast(uint spellId)
|
||||
{
|
||||
RuntimeSpellCastState? cast;
|
||||
lock (_gate)
|
||||
cast = _cast;
|
||||
return cast is not null && cast.Cast(spellId) == CastRequestResult.Sent;
|
||||
}
|
||||
|
||||
public void Dispose()
|
||||
{
|
||||
lock (_gate)
|
||||
{
|
||||
if (_disposed)
|
||||
return;
|
||||
_disposed = true;
|
||||
DetachLocked();
|
||||
}
|
||||
_knownSelfBuffs = Array.Empty<PluginSpellInfo>();
|
||||
_enchantments = Array.Empty<PluginActiveEnchantment>();
|
||||
}
|
||||
}
|
||||
|
|
@ -9,13 +9,15 @@ public sealed class AppPluginHost : IPluginHost
|
|||
IGameState state,
|
||||
IEvents events,
|
||||
ISelectionService selection,
|
||||
IUiRegistry ui)
|
||||
IUiRegistry ui,
|
||||
IAutomationSurface automation)
|
||||
{
|
||||
Log = log;
|
||||
State = state;
|
||||
Events = events;
|
||||
Selection = selection;
|
||||
Ui = ui;
|
||||
Automation = automation;
|
||||
}
|
||||
|
||||
public bool HasUi => true;
|
||||
|
|
@ -24,4 +26,5 @@ public sealed class AppPluginHost : IPluginHost
|
|||
public IEvents Events { get; }
|
||||
public ISelectionService Selection { get; }
|
||||
public IUiRegistry Ui { get; }
|
||||
public IAutomationSurface Automation { get; }
|
||||
}
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue