acdream/docs/plugin-ui-markup.md

Plugin UI markup

SSOT for AcDream.Plugin.Abstractions.IUiRegistry's markup vocabulary — every element and attribute a plugin can put in the KSML-style XML it hands the host via AddPanel/RegisterPanel/RegisterPanelContent, the {Binding} rules those attributes follow, the DAT-icon grammar (Slice B), and the movable plugin shelf (Slice A). Both slices are recorded in plans/2026-09-06-plugin-shelf-and-dat-icons.md; this page is the day-to-day reference for writing a panel, that plan is the design record.

Plugins stay BCL-only: nothing in AcDream.Plugin.Abstractions references App/UI or Core.Items types. A plugin hands the host raw ids (spell ids, object guids, DAT indices); the host owns every texture, every composited icon, and the parser that turns markup into a live UiElement tree (AcDream.App.UI.MarkupDocument).

Registering a panel

host.Ui.AddPanel(
    new PluginPanelDescriptor("main", "MossTank")
    {
        IconText = "MT",             // fallback initials if IconSurfaceId is 0
        IconSurfaceId = 0x06002C41,  // Decal-style bare index OR a full DID — both normalize
        StartVisible = true,
        ShowInSidePanel = true,
    },
    Path.Combine(pluginDirectory, "mosstank.xml"),
    binding);

RegisterPanel (same signature, returns IDisposable) removes the window independently of the plugin's own lifetime. RegisterPanelContent takes an in-memory KSML string instead of a file path — the route to reach for when a panel is small enough not to need its own shipped .xml asset.

Every registered window gets a stable persisted key (plugin:{pluginId}:{windowId}), drag, resize (where the markup opts in), the global UI lock, and a button in the shared plugin shelf (ShowInSidePanel = true, the default). Hiding or minimizing a window never disables the plugin or pauses its Tick.

The {Binding} rule

Every attribute that isn't a plain literal is either:

• a literal — a number, color, or string typed directly in the markup, or
• a binding — {PropertyName}, resolved once at Build time against the binding object's public properties/Action/Action<T> members via reflection, then re-read every frame through a Func<T> (or invoked live for actions). A plugin updates its panel by assigning a property; it never touches UiElement objects directly, and never from a thread other than the one that calls Tick.

A binding failure's severity is per-attribute, not one blanket rule — see the table below. An unrecognized {Prop} that resolves loudly (any row marked "Throws") throws FormatException at Build, the same moment any other malformed attribute throws, never silently at draw time. The attributes marked "Silent" instead fall back to something visible-but-harmless at runtime (the literal text, null, or 0) — a plugin author who typos one of those sees a wrong-looking value on screen rather than a crash, so double check those four against the markup by eye.

Attribute(s)	On a missing/mistyped {Prop}	Bound CLR type
label text, field text, menu selected, tooltip (any element)	Silent — BindString falls back to the literal attribute text itself (a typo'd {Typo} renders as the literal string {Typo})	string (via .ToString())
meter cur, meter max	Silent — BindUint returns null (the meter shows no cur/max)	uint? (accepts any integral type)
meter fill, slider value	Silent — BindFloat returns 0	float?/float
list items, menu items	Throws	IEnumerable<string>
list colors	Silent if omitted (no color override); throws if present but mistyped	IEnumerable<uint> or IEnumerable<int> (shared BindUintList)
list icons (Slice B)	Throws if present but mistyped; omitting it entirely means no icon column at all. A negative int element is silent: it maps to 0u (no icon for that row), matching the scalar did/spell/item row above	IEnumerable<uint> or IEnumerable<int>
<icon>/<button icon> did/spell/item bindings (Slice B)	Build-time: throws only for a missing bound property (or, for a literal, one that isn't valid hex/decimal) — the binder never checks the property's static CLR type. Draw-time: a resolved value that is negative or above uint.MaxValue is silent (maps to 0u, draws nothing); a resolved value that cannot convert to a number at all throws InvalidCastException/FormatException from the draw, not from Build	any integral type (uint, int, long, ushort, a nullable of one, …) via Convert.ToUInt32
list selected	Throws (required int reader)	int
tab selected, toggle checked	Throws (required bool reader)	bool
root panel visible	Throws (required bool reader; see the root-only note below)	bool
onclick (button/tab/toggle)	Throws	Action
slider onchange	Throws	Action<float>
field onchange, field onsubmit, menu onchange	Throws	Action<string>
list onchange	Throws	Action<int>
column items (type="text")	Throws — REQUIRED, unlike the single-column list's own items sugar it mirrors	IReadOnlyList<string>
column colors (type="text")	Silent if omitted (no per-row override, same rule as list colors); throws if present but mistyped	IReadOnlyList<uint> or IReadOnlyList<int>
column values (type="check")	Throws — REQUIRED (there is no "no check column" fallback the way list icons has "no icon column")	IReadOnlyList<bool>
column values (type="icon")	Throws — REQUIRED	IReadOnlyList<uint> or IReadOnlyList<int>
column onchange (type="check")	Throws — REQUIRED (unlike the list's own optional onchange)	Action<int> (row index)
column onclick (type="icon")	Throws — REQUIRED	Action<int> (row index)

The icon-id row is the one binding here whose failure mode depends on WHEN you look: a typo'd property name is caught immediately at Build, but a property that exists yet holds the wrong kind of value at runtime is only ever discovered later, from inside a live draw.

Elements

Every element name is validated at Build: an unknown or miscased tag (e.g. <Icon>, <butotn>) throws FormatException rather than silently vanishing from the built tree.

Element	Purpose	Key attributes
panel (root)	The window itself	x y w h title resize visible
group	Transparent layout container	x y w h background border visible
label	Static or bound text	x y text color
button	Clickable rect + caption (+ Slice B icon)	x y w h text color background border onclick icon iconkind
icon	Slice B: a standalone DAT icon	x y w h did spell item tooltip
meter	Retail-style nine-slice bar	x y w h fill cur max color anchor backleft/backtile/backright frontleft/fronttile/frontright
tab	Selectable tab button	x y w h text selected onclick
toggle	Lamp-style checkbox	x y w h text checked onclick color
slider	Horizontal scalar	x y w h value onchange
field	Single-line editable text	x y w h text maxlength clearonsubmit onchange onsubmit color background
menu	Dropdown selector	x y w h items selected onchange rows rowheight openupward
list	Scrollable row list (+ Slice B icon column, + Campaign VT slice 1 multi-column)	x y w h selected onchange rowheight + either the single-column items colors icons iconkind, or one-to-many <column> children (see "Columns" below) — never both

Common to every element via ApplyCommon: name/id (a stable control name), visible (literal true/false or a bound bool property), enabled (same rule), and tooltip (a literal string or {Binding} shown through retail's own runtime tooltip popup, empty/whitespace treated as no tooltip). The root <panel> is the one exception: it does not go through ApplyCommon (no name/enabled/tooltip), and its visible attribute accepts a {Binding} only — a literal visible="true" on the root is not parsed (unlike every child element, where a literal is fine).

Multi-column lists are real (Campaign VT slice 1 Part B, below) — a <list> with <column> children is no longer limited to one padded text column. A <list> with no <column> children stays exactly the older single-column form (items/colors/icons/iconkind on the element itself); the two forms are mutually exclusive on one element.

list colors' values are 0xRRGGBB (opaque, no alpha channel), while every color=/background=/border= attribute elsewhere is #AARRGGBB (alpha first) — the two grammars look similar but are not interchangeable.

Every hex literal (did, 0x id bindings, list colors entries) requires the 0x prefix to parse as hex; an all-digit string with no prefix (did="165") parses as decimal, not hex — did="165" and did="0x165" are different ids.

The icon-id grammar (Slice B)

Decal/VirindiViewService plugins (the reference usage this ported: MosswartMassacre's HudPictureBox.Image assignments, fed from Decal's FileService.SpellTable/SkillTable icon columns) hand out bare portal.dat indices — small integers, not full 0x06xxxxxx RenderSurface DIDs. acdream's host normalizes every icon id through one function so both styles work everywhere an icon id is accepted:

// AcDream.Plugin.Abstractions.PluginIcons
static uint Normalize(uint idOrIndex);
//   0                -> 0                (no icon)
//   7735             -> 0x06001E37       (bare index -> RenderSurface DID)
//   0x00FFFFFF       -> 0x06FFFFFF       (largest bare index, just below the boundary)
//   0x01000000       -> 0x01000000       (AT the boundary -> already a DID, unchanged)
//   0x06002D14       -> 0x06002D14       (already a DID, unchanged)

The boundary is 0x01000000: any value below it is treated as a bare Decal-style index and gets the 0x06000000 RenderSurface block prefix added; any value at or above it (including 0x01000000 itself) is assumed to already be a resolvable DID and passes through unchanged.

The host applies Normalize at every did-shaped sink: the descriptor's IconSurfaceId (drawn on the plugin shelf button), and every <icon did> / <button icon> (iconkind="did") / <list icons> (iconkind="did") value — literal or bound, re-normalized every frame for a bound value. A plugin never needs to call Normalize itself; handing the host either a Decal-style index or a full DID produces the same drawn icon.

Plugin-facing records that already carry full retail RenderSurface DIDs (PluginSpellInfo.IconId, PluginSkillInfo.IconId, PluginInventoryItem.IconId, PluginWorldObject.IconId) are not re-normalized — they are already in DID space, read straight from the client's SpellTable/SkillTable/object state. Normalize only matters at a markup did sink, where a plugin author might type a bare index by hand.

Do NOT add 0x06000000 to any of the four IconId records above by hand — they are already full DIDs, not bare indices. PluginSkillInfo.IconId in particular comes straight from SkillBase.IconId, and retail's own UIRegion::SetImageByDID(SkillBase._iconID) (@0x004f150e) draws that field directly as a DID with no +0x06000000 step of its own — adding the block prefix again would double-normalize it and resolve nothing (see src/AcDream.App/UI/Layout/SampleData.cs:69-83 for the real values: Melee Defense is 0x06000165, never 7735/0x165, in that field).

API-v1 note: IconId is a positional/init member on each of the four records above, so it participates in record equality (Equals/GetHashCode) along with every other field. Plugin code that compares two PluginSpellInfo/PluginSkillInfo/PluginInventoryItem/PluginWorldObject values for equality now also compares their IconId — harmless for code built against the new host (both sides fill it identically), but worth knowing if you see an equality check that used to succeed start failing against a host that populates IconId where an older one left it 0.

The three icon sources

Every icon-bearing attribute (<icon>'s did/spell/item, <button icon>, <list icons>) resolves through one of three sources, selected by which attribute is set (<icon>) or by iconkind (<button>/<list>, default "did"):

Source	What it draws	Backing API
did	The raw RenderSurface art at that DID, nothing composited on top	IMarkupIconResolver.ResolveDid (a plain sprite resolve, after PluginIcons.Normalize)
spell	Retail's composited spell icon: power-level backing + spell art + reversed/normal tint + self/fellow-targeted overlay	IconComposer.GetSpellIcon (retail ClientMagicSystem::CompositeSpellIcon)
item	Retail's composited item icon for a live object id: type-default underlay + custom underlay + base icon + custom overlay + effect recolor	IconComposer.GetIcon, reading the id's fields from the same ClientObjectTable the inventory UI already uses

did accepts a literal (did="7735" decimal, or did="0x06002D14" hex) or a binding (did="{IconDid}", a uint property re-read every frame). spell and item are almost always bindings (spell="{SpellId}", item="{ObjectId}") but accept the same literal grammar. Any of the three resolving to 0, or the resolver returning no texture, draws nothing — never a placeholder, never a throw.

A did icon is not blitted raw. It is drawn the way retail draws every icon it composites (IconData::RenderIcons with no overlay and no effects): the art's pure-white pixels are the DAT's "recolor me" key and are replaced with the solid-black fallback tile, exactly as a mundane item in the inventory. Raw art shows a white ring around the icon (Decal's HudPictureBox draws it that way); acdream does not. Art without any pure-white pixel is unaffected.

<icon>

<icon x="8" y="8" w="32" h="32" did="7735" tooltip="Decal-style index"/>
<icon x="48" y="8" w="32" h="32" did="0x06002D14"/>
<icon x="88" y="8" w="32" h="32" spell="{SpellId}" tooltip="{SpellName}"/>

Exactly one of did/spell/item must be present — two sources on one <icon> throws FormatException at Build. w/h default to 32 (retail's standard icon size) when omitted. The sprite is drawn nearest-filtered, aspect-preserved, and centered inside the w×h box — a non-square source never stretches. A tooltip attribute makes the icon a real hit-test target (it is click-through otherwise, so it never steals clicks meant for something underneath it).

<icon> derives its kind from WHICH of did/spell/item is set — unlike <button>/<list>, it has no per-element iconkind to disambiguate. Putting iconkind on an <icon> throws FormatException at Build ("iconkind applies to button and list; icon derives its kind from did/spell/item") rather than silently ignoring it.

<button icon="..." iconkind="did|spell|item">

<button x="12" y="68" w="120" h="24" text="Report"
        icon="0x06002D14" onclick="{Report}"/>

The icon draws flush left inside the button; the caption's centering region shifts right to make room. text may be empty for an icon-only button. iconkind defaults to "did".

<list icons="{IconIds}" iconkind="did|spell|item">

<list x="12" y="100" w="256" h="108"
      items="{SpellRows}" icons="{SpellIds}" iconkind="spell"
      selected="{SelectedIndex}"/>

icons is an IEnumerable<uint> (or IEnumerable<int>) binding parallel to items — Decal's IconColumn convention: a leading square column, RowHeight - 2 pixels wide, one icon per row. A row past the end of the icons list, or an id that resolves to nothing, draws no icon for that row (the text still draws, just without an icon). Omitting icons entirely keeps the list exactly as it was before Slice B (full-width text, no column).

iconkind is per-<list>, not per-row: every id in one list's icons binding is resolved the same way (all did, all spell, or all item). There is no way to mix kinds within a single list. Two consequences:

• If a plugin's data genuinely mixes id spaces (some rows are raw DIDs, some are spell ids needing a composited badge), it must pre-normalize/pre-resolve outside the markup and expose ONE consistent IEnumerable<uint> of did-space ids — iconkind="did" on the list.
• retail's composited spell badge (power-level backing + tint + self/fellow overlay) can only be reached through iconkind="spell" with real spell ids — there is no DID that already IS the composited result, so a list that wants the badge look has no did-space escape hatch.

MosswartMassacre-style example — a list column composited from spell ids, with the spell's own raw art DID printed alongside the name for comparison:

// iconkind="spell": the values MUST be spell ids (what ResolveSpell composites
// a badge from), NOT the spell's raw IconId — those are different id spaces.
public IEnumerable<uint> SpellIds =>
    host.Automation.Spells.KnownSelfBuffs.Select(s => s.SpellId);
public IEnumerable<string> SpellRows =>
    host.Automation.Spells.KnownSelfBuffs.Select(
        s => $"{s.Name} (icon 0x{s.IconId:X8})");

<list items="{SpellRows}" icons="{SpellIds}" iconkind="spell" .../>

(A list backed by PluginSpellInfo.IconId directly — the spell's own raw art tile, no composited badge — uses iconkind="did" instead, with icons yielding IconId rather than SpellId.)

Columns (Campaign VT slice 1 Part B)

VVS's HudList (the VirindiViewService list control VTank's own mainView.xml uses) supports N independently-typed columns per row — text, checkbox, and icon cells side by side in one scrolling grid, each with its own Click(row, col). acdream's <list> matches this by letting a <list> declare <column> children instead of the single-column items/colors/icons attributes:

<list x="8" y="24" w="256" h="120" rowheight="17"
      selected="{SelectedMonster}" onchange="{SelectMonster}">
  <column type="text"  width="140" items="{MonsterNames}"/>
  <column type="check" width="24"  values="{MonsterFester}"  onchange="{ToggleFester}"/>
  <column type="icon"  width="24"  iconkind="did" values="{MonsterIcons}" onclick="{PingMonster}"/>
</list>

This mirrors VTank's own Monsters tab (a name column plus several boolean flag columns plus an icon-button column) — see docs/research/vtank-kb/08-ui-views.md §3's "Multi-column lists with typed columns" gap and its proposed extension, which this implements verbatim.

<column> attribute grammar

Attribute	Applies to	Required	Meaning
type	every column	yes	text, check, or icon — any other value throws FormatException at Build
width	every column	no (defaults to 0)	Column width in px. The LAST column in a <list> ignores its own declared width and always absorbs whatever room remains after every earlier column — recomputed every frame off the list's live width, so a resizable list re-flows its last column like every other retained widget
items	type="text"	yes	{IReadOnlyList<string>} — one row of text per index
colors	type="text"	no	{IReadOnlyList<uint>}, 0xRRGGBB per row (same grammar as the single-column list's own colors); omitted rows (or the whole attribute) fall back to the list's TextColor
values	type="check"	yes	{IReadOnlyList<bool>} — the checked state per row
onchange	type="check"	yes	{Action<int>} — fired with the ROW INDEX on a click anywhere in the cell; the plugin flips its own bool, the column never mutates values' backing collection itself
values	type="icon"	yes	{IReadOnlyList<uint>} (or IReadOnlyList<int>) — one icon id per row, same id-space rules as list icons
iconkind	type="icon"	no (defaults "did")	did/spell/item, same three-source dispatch as <list icons iconkind> above — one kind per column, not per row
onclick	type="icon"	yes	{Action<int>} — fired with the ROW INDEX on a click anywhere in the cell

Unlike the single-column list's optional icons/onchange, a check/icon column's own values and onchange/onclick are required — a column that can never fire anything, or has nothing to draw, is a Build-time author error, not a silently-inert control. A <column> with an unrecognized type, a missing required binding for its type, or any <list> child element that isn't <column> at all, throws FormatException at Build. A <list> with <column> children cannot ALSO use the single-column items/colors/icons attributes on the <list> element itself — pick one form per list.

Row count, selection, and clicks

Row count is the longest bound column (a text column with 20 rows next to a check column with only 5 simply draws 15 rows of empty checkboxes — short columns never truncate the whole list). The list's own selected/onchange attributes keep exactly their single-column meaning: a click in a text column selects that row (and fires the list's onchange with the row index, same as today). A click in a check or icon column instead fires that column's own onchange/onclick and does not change the list's selection — VVS's per-cell Click(row, col) folded into a per-column callback, since acdream's binding model is per-attribute rather than per-cell. Scrolling works exactly as the single-column list already does.

No header row

VVS's HudList has no built-in header row either — the column-caption glyphs seen in VTank's own mainView.xml (e.g. the Monsters tab's single-letter "F"/"B"/"G"/"I"/… flag headers) are ordinary StaticText controls placed manually above the list. acdream matches this for free: put a <label> (or several, one per column, hand-positioned) directly above the <list> — there is no dedicated header markup to learn.

Check-column glyph

A type="check" cell draws with the exact same five-band lamp glyph as <toggle> (UiMarkupToggle's checked/unchecked colors and DrawLamp primitive), so a column checkbox reads identically to every other checkbox in the client rather than a bespoke box-and-tick.

Backward compatibility

A <list> with no <column> children is byte-for-byte the original single-text-column widget — every existing panel (including every current MossTank tab) keeps working unchanged; <column> is additive, not a migration.

The plugin shelf (Slice A)

The shelf (AcDream.App.UI.PluginSidePanel) is the right-edge strip of per-plugin-window buttons. It is a real retained window (RetailWindowManager key plugin-shelf), so it gets drag, the global UI lock, and persisted position/visibility/collapsed state for free, exactly like every other window.

• Drag: a grip strip across its top (three short dashes) is the move handle. Dragging elsewhere on the shelf (the buttons themselves, the padding between them) does not move the window.
• Collapse: a small >/< toggle at the grip's right end (expanded shows >, collapsed shows <) shrinks the shelf to a 28px-tall, button-sized tab (deliberately findable-sized, not a thin sliver) rather than just the grip band; button entries stay laid out underneath so expanding is instant. Persists through the same window-state channel as position/visibility.
• Hide/show: Shift+Ctrl+F1 (retail's plugin-manager chord, InputAction.TogglePluginManager — acdream has no separate plugin manager, so this is its honest home). Hiding the shelf never disables a plugin or touches any individual plugin window's own visibility; a new plugin window registering while the shelf is hidden does not un-hide it. If no plugin has registered a shelf entry yet, the chord reports "No plugin windows are registered." instead.
• Default dock: with no saved layout, the shelf sits at the right screen edge, top 116px — until the user drags it (or a saved layout restores a different position), after which it stays put and growth preserves whatever corner it's anchored from.

Testing conventions

MarkupDocumentTests/MarkupIconTests build panels with a fake resolve/IMarkupIconResolver (_ => (1u, 32, 32) for sprites; a small in-test class recording which id/kind it was asked to resolve) rather than a live DAT — see tests/AcDream.App.Tests/UI/. PluginSidePanelTests exercises the shelf's drag/collapse/hide/persistence behavior against a bare UiRoot. MarkupListColumnsTests covers the Columns extension above: per-column binding-type validation, draw-level column-offset/clipping/check-glyph pins against the same recording-renderer apparatus, hit-test routing (text selects; check/icon fire their own callback and never touch selection), and a backward-compatibility proof that a column-less <list> is unaffected.