feat(D.5.3a): selected-object meter — Health bar + name on the action bar

Port of gmToolbarUI::HandleSelectionChanged (acclient_2013_pseudo_c.txt:198635).
When the player selects a world object the action bar's bottom strip shows the
object name + (for player/pet/attackable targets) a live Health meter; deselect
clears it. Mana (#140) + stack slider deferred.

- SelectedObjectController (new): clear-then-populate on selection change; sets
  name (UiText child, VitalsController pattern), overlay state (ObjectSelected /
  StackedItemSelected via UiDatElement.ActiveState), shows the health meter and
  sends QueryHealth for health targets. Subscribes via a delegate seam (no
  GameWindow coupling).
- GameWindow: _selectedGuid field -> SelectedGuid property + SelectionChanged
  event (fires on actual change only); 3 write sites converted, reads untouched.
  All selection-write paths (LMB pick, Tab/Q, despawn-clear via Tick()) run on
  the render thread, so the event-driven UI mutation is single-threaded.
- WorldSession.SendQueryHealth (0x01BF) — wraps SocialActions.BuildQueryHealth.
- DatWidgetFactory.BuildMeter: handle the single-image toolbar meter shape
  (back-track on the element's own DirectState, fill on one Type-3 child). The
  sprites go in the TILE slot (DrawMode=Normal tiles to full bar geometry per
  UIElement_Meter::DrawChildren) — a left-cap assignment would gap/clamp a
  sub-140px sprite. Vitals 3-slice path unchanged.
- ToolbarController.HiddenIds: A1 (health) now owned by SelectedObjectController;
  A2 (mana) + A4 (stack) stay hidden (deferred) so their dat back-tracks don't
  render as stray empty bars.

Adversarial Opus review found + fixed: the mana-meter orphan (A2 left unhidden)
and the meter tile-vs-cap render bug (C1). Divergence rows AP-46 (health gate
approximation: IsLiveCreatureTarget vs IsPlayer||pet||attackable) + AP-47
(meter shown on select vs on UpdateHealth reply). Spec §5 corrected.

Build + full test suite green (2,684 passed / 4 skipped). Health meter render
fidelity (full-width fill + fraction mapping) pending the user's visual gate.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Erik 2026-06-18 22:47:24 +02:00
parent e8562fc4e2
commit 6636e50c2a
11 changed files with 851 additions and 30 deletions

View file

@ -619,6 +619,8 @@ public sealed class GameWindow : IDisposable
private AcDream.App.UI.UiHost? _uiHost;
// Phase D.5.1 — toolbar controller (kept for lifetime clarity; mirrors _chatWindowController pattern).
private AcDream.App.UI.Layout.ToolbarController? _toolbarController;
// Phase D.5.3a — selected-object strip controller (name, overlay state, health meter).
private AcDream.App.UI.Layout.SelectedObjectController? _selectedObjectController;
// Phase D.2b Task 9 — plugin UI registrations buffered before OnLoad; drained in OnLoad.
private readonly AcDream.App.Plugins.BufferedUiRegistry? _uiRegistry;
// Phase I.2: ImGui debug panel ViewModel. Lives for as long as
@ -846,6 +848,21 @@ public sealed class GameWindow : IDisposable
private readonly Dictionary<uint, AcDream.Core.Net.WorldSession.EntitySpawn> _lastSpawnByGuid = new();
// Current selection: written by Q-cycle (combat) and LMB click (interact); cleared on entity despawn.
private uint? _selectedGuid;
/// <summary>Fires when the selected world object changes (retail gmToolbarUI selection-change event,
/// acclient_2013_pseudo_c.txt:198635). Private: only the internal SelectedObjectController subscribes.</summary>
private event Action<uint?>? SelectionChanged;
/// <summary>Currently-selected world object guid. The setter fires <see cref="SelectionChanged"/> only on
/// an actual change (dedup), so all writes go through here; reads may use the field directly.</summary>
private uint? SelectedGuid
{
get => _selectedGuid;
set
{
if (_selectedGuid == value) return;
_selectedGuid = value;
SelectionChanged?.Invoke(value);
}
}
// B.6/B.7 (2026-05-16): pending close-range action that will be fired
// once the local auto-walk overlay reports arrival (body has finished
@ -2003,6 +2020,19 @@ public sealed class GameWindow : IDisposable
warDigits: toolbarWarDigits,
emptyDigits: toolbarEmptyDigits);
// Phase D.5.3a — selected-object strip (name, overlay state, health meter).
// Analogue of retail gmToolbarUI::HandleSelectionChanged
// (acclient_2013_pseudo_c.txt:198635).
_selectedObjectController = AcDream.App.UI.Layout.SelectedObjectController.Bind(
toolbarLayout,
subscribeSelectionChanged: h => SelectionChanged += h,
isHealthTarget: IsLiveCreatureTarget,
name: g => Objects.Get(g)?.Name,
healthPercent: g => Combat.GetHealthPercent(g),
stackSize: g => (uint)(Objects.Get(g)?.StackSize ?? 0),
sendQueryHealth: g => _liveSession?.SendQueryHealth(g),
datFont: vitalsDatFont);
var toolbarRoot = toolbarLayout.Root;
// Wrap the dat content in the universal 8-piece beveled window chrome —
// the SAME UiNineSlicePanel used by the vitals and chat windows. The
@ -3708,7 +3738,7 @@ public sealed class GameWindow : IDisposable
_entitiesByServerGuid.Remove(serverGuid);
_lastSpawnByGuid.Remove(serverGuid);
if (_selectedGuid == serverGuid)
_selectedGuid = null;
SelectedGuid = null;
if (logDelete)
_lightingSink?.UnregisterOwner(existingEntity.Id);
@ -11568,7 +11598,7 @@ public sealed class GameWindow : IDisposable
if (picked is uint guid)
{
_selectedGuid = guid;
SelectedGuid = guid;
string label = DescribeLiveEntity(guid);
Console.WriteLine($"[B.4b] pick guid=0x{guid:X8} name={label}");
// B.7 (2026-05-15): one-shot per-pick diagnostic so we can
@ -11958,7 +11988,7 @@ public sealed class GameWindow : IDisposable
bestGuid = guid;
}
_selectedGuid = bestGuid;
SelectedGuid = bestGuid;
if (bestGuid is { } selected)
{
string label = DescribeLiveEntity(selected);

View file

@ -90,11 +90,11 @@ public static class DatWidgetFactory
// ── Meter ────────────────────────────────────────────────────────────────
/// <summary>
/// Builds a <see cref="UiMeter"/> and populates its six 3-slice sprite ids by
/// reading the meter's grandchild image elements (format doc §11).
/// Builds a <see cref="UiMeter"/> and populates its sprite ids from the meter's
/// child/grandchild elements (format doc §11). Two shapes are handled:
///
/// <para>
/// Structure the importer produces for each meter (UIElement_Meter):
/// <b>3-slice shape</b> (vitals meters — 2 Type-3 containers, each with 3 image grandchildren):
/// <code>
/// meter (Type 7)
/// ├── back-layer container (Type 3, lower ReadOrder — drawn first / behind)
@ -106,13 +106,27 @@ public static class DatWidgetFactory
/// │ ├── center image (→ front-tile sprite)
/// │ ├── right-cap image (→ front-right sprite)
/// │ └── expand overlay (named "ShowDetail"/"HideDetail" only — NO DirectState — IGNORED)
/// └── text label (Type 0) (IGNORED — Fill/Label providers bound by VitalsController in Task 6)
/// └── text label (Type 0) (IGNORED — Fill/Label providers bound by VitalsController)
/// </code>
/// </para>
///
/// <para>
/// <b>Single-image shape</b> (toolbar selected-object meters 0x100001A1/0x100001A2 — 1 Type-3
/// child, no grandchildren): the back-track sprite is on the meter element's own DirectState;
/// the fill sprite is on the single Type-3 child's own DirectState. Both are placed in the
/// TILE slot (Back/FrontTile) with left/right caps 0, so <see cref="UiMeter.DrawHBar"/> tiles
/// them across the full bar geometry (DrawMode=Normal) and clips the fill to the fraction.
/// (retail: gmToolbarUI::HandleSelectionChanged :198635, UIElement_Meter::Initialize :123328)
/// <code>
/// meter (Type 7) [DirectState "" → back-track sprite, e.g. 0x0600193E]
/// └── fill container (Type 3) [DirectState "" → fill sprite, e.g. 0x0600193F]
/// </code>
/// </para>
///
/// <para>
/// <see cref="UiMeter.Fill"/> and <see cref="UiMeter.Label"/> are NOT set here.
/// They are bound to the live stat providers in Task 6 (VitalsController).
/// They are bound to the live stat providers by the controller (VitalsController /
/// SelectedObjectController).
/// </para>
/// </summary>
private static UiMeter BuildMeter(ElementInfo info,
@ -132,23 +146,53 @@ public static class DatWidgetFactory
.OrderBy(c => c.ReadOrder)
.ToList();
if (containers.Count != 2)
Console.WriteLine($"[D.2b] meter 0x{info.Id:X8}: {containers.Count} Type-3 slice containers (expected 2) — bars may render as solid-color fallback.");
if (containers.Count >= 1)
{
var (l, t, r) = SliceIds(containers[0]);
m.BackLeft = l;
m.BackTile = t;
m.BackRight = r;
}
if (containers.Count >= 2)
{
var (l, t, r) = SliceIds(containers[1]);
m.FrontLeft = l;
m.FrontTile = t;
m.FrontRight = r;
// Vitals 3-slice shape: two Type-3 containers each holding 3 grandchild images
// (left-cap / center-tile / right-cap). Back is the lower ReadOrder; front is higher.
var (bl, bt, br) = SliceIds(containers[0]);
m.BackLeft = bl;
m.BackTile = bt;
m.BackRight = br;
var (fl, ft, fr) = SliceIds(containers[1]);
m.FrontLeft = fl;
m.FrontTile = ft;
m.FrontRight = fr;
}
else if (containers.Count == 1)
{
// Single-image shape used by the toolbar selected-object meters
// (health 0x100001A1, mana 0x100001A2).
// - The back-track sprite lives on the meter ELEMENT's own DirectState ("" key of
// info.StateMedia) — not on any grandchild image. e.g. health back = 0x0600193E.
// - The fill sprite lives on the single Type-3 child's own DirectState ("" key of
// containers[0].StateMedia). e.g. health fill = 0x0600193F.
// The fill child has NO image grandchildren, so SliceIds would return all-zero —
// read the container's StateMedia directly instead.
//
// These go in the TILE slot (not the left-cap slot): the sprites are DrawMode=Normal,
// which retail renders as "tile at native width to fill the full element geometry"
// (format doc §6; the generic UiDatElement.OnDraw Normal path; UIElement_Meter::
// DrawChildren :123574 clips the child's FULL 140px geometry box to the fill fraction).
// With the sprite on BackLeft instead, UiMeter.DrawHBar would clamp the cap to the
// sprite's NATIVE width (capL = min(nativeW, 140)) — leaving a right-side gap and
// mapping the fill fraction to native width when nativeW < 140. The tile slot makes
// midW = full bar width, so the back tiles across all 140px and the front clips to
// 140*fraction correctly for any native sprite width (left/right caps unused = 0).
// (retail: gmToolbarUI::HandleSelectionChanged :198635 / UIElement_Meter::DrawChildren :123574)
m.BackLeft = 0;
m.BackTile = info.StateMedia.TryGetValue("", out var bm) ? bm.File : 0u;
m.BackRight = 0;
m.FrontLeft = 0;
m.FrontTile = containers[0].StateMedia.TryGetValue("", out var fm) ? fm.File : 0u;
m.FrontRight = 0;
}
else
{
// Count == 0: no Type-3 containers at all — genuinely malformed meter dat.
Console.WriteLine($"[D.2b] meter 0x{info.Id:X8}: {containers.Count} Type-3 slice containers (expected 1 or 2) — bars may render as solid-color fallback.");
}
return m;

View file

@ -0,0 +1,208 @@
using System;
using System.Numerics;
using AcDream.App.UI;
namespace AcDream.App.UI.Layout;
/// <summary>
/// Controller for the action bar's selected-object strip (ids 0x1000019F0x100001A1).
/// Analogue of retail <c>gmToolbarUI::HandleSelectionChanged</c>
/// (<c>docs/research/named-retail/acclient_2013_pseudo_c.txt:198635</c>).
///
/// <para>
/// On selection change: clears the strip (name, overlay state, health meter), then
/// if a guid is provided it sets the name, puts the overlay field into the appropriate
/// state ("ObjectSelected" or "StackedItemSelected"), and for health-bearing targets
/// shows the health meter and sends a <c>QueryHealth (0x01BF)</c> request.
/// </para>
///
/// <para>
/// <strong>Divergence — meter-visible timing.</strong>
/// Retail makes the health meter visible from <c>RecvNotice_UpdateObjectHealth</c>
/// (when the queried value arrives, cite HandleSelectionChanged:198757).
/// acdream shows it immediately on select (fill polls <see cref="CombatState.GetHealthPercent"/>
/// which returns 1.0 until the reply lands). Recorded in the divergence register.
/// </para>
///
/// <para>
/// <strong>Divergence — health-target gate approximation.</strong>
/// Retail gates on <c>IsPlayer() || pet_owner || ObjectIsAttackable()</c>
/// (cite HandleSelectionChanged:198754). acdream uses <c>IsLiveCreatureTarget</c>
/// (the <c>ItemType.Creature</c> flag). Recorded in the divergence register.
/// </para>
/// </summary>
public sealed class SelectedObjectController
{
// ── Element ids (toolbar LayoutDesc 0x21000016) ─────────────────────────
/// <summary>Selected-object name element id.</summary>
public const uint NameId = 0x1000019F;
/// <summary>Selected-object overlay field element id (states: ObjectSelected / StackedItemSelected).</summary>
public const uint OverlayId = 0x100001A0;
/// <summary>Selected-object health meter element id.</summary>
public const uint HealthMeterId = 0x100001A1;
// ── Found elements (any may be null for partial/test layouts) ───────────
private readonly UiElement? _name;
private readonly UiDatElement? _overlay;
private readonly UiMeter? _healthMeter;
// ── Captured delegates ───────────────────────────────────────────────────
private readonly Func<uint, bool> _isHealthTarget;
private readonly Func<uint, string?> _name_;
private readonly Func<uint, float> _healthPercent;
private readonly Func<uint, uint> _stackSize;
private readonly Action<uint> _sendQueryHealth;
// ── Live state (read by closures on the per-frame draw path) ────────────
private uint? _current;
private string? _currentName;
/// <summary>White label color for the name line.</summary>
private static readonly Vector4 NameColor = new(1f, 1f, 1f, 1f);
private SelectedObjectController(
ImportedLayout layout,
Action<Action<uint?>> subscribeSelectionChanged,
Func<uint, bool> isHealthTarget,
Func<uint, string?> name,
Func<uint, float> healthPercent,
Func<uint, uint> stackSize,
Action<uint> sendQueryHealth,
UiDatFont? datFont)
{
_isHealthTarget = isHealthTarget;
_name_ = name;
_healthPercent = healthPercent;
_stackSize = stackSize;
_sendQueryHealth = sendQueryHealth;
// Find elements — silently skip absent ones (partial/test layouts).
_name = layout.FindElement(NameId);
_overlay = layout.FindElement(OverlayId) as UiDatElement;
_healthMeter = layout.FindElement(HealthMeterId) as UiMeter;
// This controller owns the health meter's initial-hidden state.
if (_healthMeter is not null)
{
_healthMeter.Visible = false;
// Fill polls live: _current holds the currently-selected guid (or null).
// Returns 0f when nothing is selected (empty bar), healthPercent(g) otherwise.
_healthMeter.Fill = () => _current is uint g ? _healthPercent(g) : (float?)0f;
}
// Attach a centered UiText child to the name element for the object name display.
// Mirrors VitalsController.BindMeter's number attach (same decoration style).
if (_name is not null)
{
var label = new UiText
{
Left = 0f,
Top = 0f,
Width = _name.Width,
Height = _name.Height,
Anchors = AnchorEdges.Left | AnchorEdges.Top | AnchorEdges.Right | AnchorEdges.Bottom,
Centered = true,
DatFont = datFont,
ClickThrough = true,
AcceptsFocus = false,
IsEditControl = false,
CapturesPointerDrag = false,
LinesProvider = () =>
{
// Returns a single white line when a name is available; empty otherwise.
var n = _currentName;
return string.IsNullOrEmpty(n)
? Array.Empty<UiText.Line>()
: new[] { new UiText.Line(n, NameColor) };
},
};
_name.AddChild(label);
}
// Register the handler LAST so the initial state is fully set up first.
subscribeSelectionChanged(OnSelectionChanged);
}
/// <summary>
/// Create and bind a <see cref="SelectedObjectController"/> to <paramref name="layout"/>.
/// Port of retail <c>gmToolbarUI::HandleSelectionChanged</c>
/// (<c>acclient_2013_pseudo_c.txt:198635</c>).
/// </summary>
/// <param name="layout">Imported toolbar layout (LayoutDesc 0x21000016).</param>
/// <param name="subscribeSelectionChanged">
/// Called once with the controller's <see cref="OnSelectionChanged"/> handler.
/// Typical host: <c>h =&gt; SelectionChanged += h</c> — keeps the controller
/// decoupled from <c>GameWindow</c>.
/// </param>
/// <param name="isHealthTarget">
/// Returns true for guids that should show a health meter (proxy for retail's
/// <c>IsPlayer() || pet_owner || ObjectIsAttackable()</c>).
/// </param>
/// <param name="name">Returns the display name for a given guid (or null if unknown).</param>
/// <param name="healthPercent">Returns the health fill fraction [0..1] for a given guid.</param>
/// <param name="stackSize">Returns the stack size for a given guid (0 or 1 = non-stacked).</param>
/// <param name="sendQueryHealth">
/// Sends retail <c>QueryHealth (0x01BF)</c>; server replies with <c>UpdateHealth (0x01C0)</c>.
/// May be a no-op when offline.
/// </param>
/// <param name="datFont">Dat font for the name label; null = debug bitmap font fallback.</param>
public static SelectedObjectController Bind(
ImportedLayout layout,
Action<Action<uint?>> subscribeSelectionChanged,
Func<uint, bool> isHealthTarget,
Func<uint, string?> name,
Func<uint, float> healthPercent,
Func<uint, uint> stackSize,
Action<uint> sendQueryHealth,
UiDatFont? datFont)
{
return new SelectedObjectController(
layout, subscribeSelectionChanged,
isHealthTarget, name, healthPercent, stackSize, sendQueryHealth, datFont);
}
/// <summary>
/// Port of <c>gmToolbarUI::HandleSelectionChanged</c>
/// (<c>acclient_2013_pseudo_c.txt:198635</c>):
/// clear-then-populate the selected-object strip on any selection change.
/// Registered via <c>subscribeSelectionChanged</c> at bind time; called by
/// <c>GameWindow.SelectionChanged</c> and by the despawn-clear path.
/// </summary>
public void OnSelectionChanged(uint? guid)
{
// ── 1. Clear first (retail: UIElement_Text::SetText + m_pSelObjectField->SetState(0)
// + SetVisible(0) on the health meter). ──────────────────────────────────────
if (_healthMeter is not null) _healthMeter.Visible = false;
if (_overlay is not null) _overlay.ActiveState = "";
_currentName = null;
// Update the backing current guid so the Fill closure reflects the new state.
_current = guid;
// ── 2. Selection == null → strip stays cleared, done. ───────────────────────────
if (guid is null) return;
uint g = guid.Value;
// ── 3. Selection != null — populate the strip. ──────────────────────────────────
// Name (displayed via the UiText child's LinesProvider reading _currentName).
_currentName = _name_(g);
// Overlay state: "StackedItemSelected" for stacked items, "ObjectSelected" otherwise.
// Retail ref: m_pSelObjectField->SetState(0x1000000b) = "ObjectSelected"
// (acclient_2013_pseudo_c.txt:198754). Stack sprite id 0x06004CF4 confirmed in toolbar dump.
if (_overlay is not null)
_overlay.ActiveState = _stackSize(g) > 1u ? "StackedItemSelected" : "ObjectSelected";
// Health meter: visible + QueryHealth for health-bearing targets.
// Divergence: retail shows the meter only when RecvNotice_UpdateObjectHealth arrives;
// acdream shows it immediately (fill reads GetHealthPercent = 1.0 until the reply).
// Retail ref: CM_Combat::Event_QueryHealth (acclient_2013_pseudo_c.txt:198757).
if (_isHealthTarget(g))
{
if (_healthMeter is not null) _healthMeter.Visible = true;
_sendQueryHealth(g);
}
}
}

View file

@ -35,10 +35,15 @@ public sealed class ToolbarController
0x100006BC, 0x100006BD, 0x100006BE, 0x100006BF,
};
// Elements hidden by default in retail gmToolbarUI::PostInit: the selected-object
// vitals meters (health/stamina/mana bars that track your target) and the stack slider.
// Elements hidden by default in retail gmToolbarUI::PostInit.
// Ids confirmed from the toolbar LayoutDesc dump.
private static readonly uint[] HiddenIds = { 0x100001A1, 0x100001A2, 0x100001A4 };
// 0x100001A1 (health meter) is now OWNED by SelectedObjectController (D.5.3a) —
// it hides A1 at bind and shows it on a health-target selection, so A1 is removed
// from here to avoid double-ownership. 0x100001A2 (mana meter) and 0x100001A4
// (stack slider) are DEFERRED features (mana #140, stack-split UI) with no controller
// yet, so they stay hidden here — otherwise their dat back-track sprites render as
// stray empty bars on the toolbar.
private static readonly uint[] HiddenIds = { 0x100001A2, 0x100001A4 };
// Four mutually-exclusive combat-mode indicator elements — exactly one visible at a time.
// Index 0 = NonCombat (peace), 1 = Melee, 2 = Missile, 3 = Magic.

View file

@ -1140,6 +1140,18 @@ public sealed class WorldSession : IDisposable
SendGameAction(body);
}
/// <summary>Send retail QueryHealth (0x01BF). Server replies UpdateHealth (0x01C0).</summary>
/// <remarks>
/// Retail anchor: <c>CM_Combat::Event_QueryHealth</c> / <c>gmToolbarUI::HandleSelectionChanged:198635</c>
/// (docs/research/named-retail/acclient_2013_pseudo_c.txt).
/// </remarks>
public void SendQueryHealth(uint targetGuid)
{
uint seq = NextGameActionSequence();
byte[] body = SocialActions.BuildQueryHealth(seq, targetGuid);
SendGameAction(body);
}
/// <summary>Send retail TargetedMeleeAttack (0x0008).</summary>
public void SendMeleeAttack(uint targetGuid, AttackHeight attackHeight, float powerLevel)
{