docs #CT1: character-panel DAT ground truth + InstalledDat pins

Campaign CT slice CT1 (docs/plans/2026-08-24-character-panel-parity-campaign.md): establishes the authored ground truth for LayoutDesc 0x2100002E that CT2-CT6 build against, so those slices port against verified DAT facts instead of guessing. No production code changed. Header findings: the PK line is authored pure white (the CT4 bug is in CharacterStatController's runtime color choice, not a DAT gap); the level color is a pale-gold (1, 0.949, 0.498) WITH an authored outline, diverging from the current hardcoded Gold constant. The stat ListBox's row-template list (LayoutDesc 0x21000045) is unreachable via the whole-layout ImportInfos overload (the #375 same-layout template-list skip filter) -- the targeted ImportInfos(dats, layoutId, elementId) overload is required, same as UiTemplateListBox's TemplateResolver already uses. The shared attribute/skill row template (0x10000248) authors a 20x20 icon flush at X=0 (current code: 16x16 at X=4), fixed 150px/100px name/value columns at X=25/X=175 (current code: a width-fraction split), and a 7px gap between the value's right edge and the row's own edge -- the scrollbar-gutter margin the owner reported missing. The Titles page roster, row template (LayoutDesc 0x2100005E), and window constraints are also pinned; the character window's root authors NO min/max size properties at all (unlike chat's self-contained window layout), and RetailUiRuntime.MountCharacter never wires DatConstraintSource -- correcting the plan's "already in-tree" claim for CT6. Also derives and pins the full CharacterTitleTable::GetCharacterTitleFromID chain (title id -> EnumMapper(0x22000041) canonical name -> compute_str_hash -> StringTable(0x2300000E) localized text), resolved via the two-level DBObj::GetDIDByEnum master-map indirection (0x25000000 -> category map -> target DID) and verified end to end against ACE's CharacterTitle.WarMage=13 -> "War Mage". This independently cross-validates RetailKeyNames' existing 0x2300000A/0x2300000B/0x23000007 constants, which turn out to be the same category-4 map's enum 4/5/3 entries. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-08-24 21:31:16 +02:00 · 2026-08-24 21:31:16 +02:00 · ca4100e76a
commit ca4100e76a
parent 45e276d380
2 changed files with 747 additions and 0 deletions
--- a/tests/AcDream.App.Tests/UI/Layout/CharacterPanelLiveDatTests.cs
+++ b/tests/AcDream.App.Tests/UI/Layout/CharacterPanelLiveDatTests.cs
@ -0,0 +1,351 @@
+using System.Numerics;
+using AcDream.App.UI.Layout;
+using DatReaderWriter;
+
+namespace AcDream.App.Tests.UI.Layout;
+
+/// <summary>
+/// Campaign CT slice CT1 (2026-08-24) pins: the DAT ground truth for the
+/// character panel (LayoutDesc <c>0x2100002E</c>) that slices CT2–CT6 build
+/// against. Findings + raw probe excerpts live in
+/// <c>docs/research/2026-08-24-campaign-ct-dat-ground-truth.md</c>. Follows
+/// the durable-pin pattern of <see cref="ScrollbarSkinLiveDatTests"/> /
+/// <see cref="TooltipSkinLiveDatTests"/> — assertions, not dumps — so a DAT
+/// revision or importer regression that silently changes any of these
+/// authored facts fails loudly instead of drifting unnoticed into CT2–CT6.
+///
+/// <para>Decomp anchors: header elements are bound by
+/// <c>gmStatManagementUI::PostInit @0x004EFD90</c>; the Titles page by
+/// <c>gmCharacterTitleUI::PostInit @0x0049A610</c>.</para>
+/// </summary>
+[Trait("Lane", "InstalledDat")]
+public sealed class CharacterPanelLiveDatTests
+{
+    private static string DatDirectory =>
+        Path.Combine(
+            Environment.GetFolderPath(Environment.SpecialFolder.UserProfile),
+            "Documents", "Asheron's Call");
+
+    private static IEnumerable<ElementInfo> Flatten(ElementInfo e)
+    {
+        yield return e;
+        foreach (var c in e.Children)
+            foreach (var d in Flatten(c))
+                yield return d;
+    }
+
+    /// <summary>
+    /// Header identity + level elements, bound by
+    /// <c>gmStatManagementUI::PostInit @0x004EFD90</c>. Pins item 4 (the PK
+    /// line is authored pure white — the CT4 bug is in the controller's
+    /// runtime color choice, NOT a DAT-reading gap) and item 5 (the level
+    /// color is a pale gold with an authored outline, not
+    /// <c>CharacterStatController</c>'s current deeper-orange
+    /// <c>Gold</c> constant). Both header occurrences (Attributes-page and
+    /// Skills-page chains) are asserted identical — the harmless
+    /// "duplicated stat-management branches" quirk documented on
+    /// <c>PrepareSkillScrollbar</c>.
+    /// </summary>
+    [InstalledDatFact]
+    public void HeaderElements_AuthorExpectedFontsAndColors()
+    {
+        using var dats = new DatCollection(DatDirectory, DatReaderWriter.Options.DatAccessType.Read);
+        ElementInfo? tree = LayoutImporter.ImportInfos(dats, 0x2100002Eu);
+        Assert.NotNull(tree);
+
+        var nameOccurrences = Flatten(tree!).Where(e => e.Id == CharacterStatController.NameId).ToList();
+        Assert.Equal(2, nameOccurrences.Count); // Attributes-page + Skills-page duplicate chains
+        foreach (var name in nameOccurrences)
+        {
+            Assert.Equal(0x40000001u, name.FontDid);
+            Assert.Equal(Vector4.One, name.FontColor);
+        }
+
+        foreach (var heritage in Flatten(tree!).Where(e => e.Id == CharacterStatController.HeritageId))
+        {
+            Assert.Equal(0x40000002u, heritage.FontDid);
+            Assert.Equal(Vector4.One, heritage.FontColor);
+            Assert.Equal(5, heritage.MarginLeft);
+            Assert.Equal(5, heritage.MarginRight);
+        }
+
+        // Item 4: PK status line is authored PURE WHITE.
+        foreach (var pk in Flatten(tree!).Where(e => e.Id == CharacterStatController.PkStatusId))
+        {
+            Assert.Equal(0x40000002u, pk.FontDid);
+            Assert.Equal(Vector4.One, pk.FontColor);
+        }
+
+        // Item 5: level color is a pale gold (~RGB 255/242/127) WITH an
+        // authored outline — CharacterStatController.Gold (1, 0.82, 0.36, 1)
+        // with no outline is a divergent hand-picked runtime color.
+        foreach (var level in Flatten(tree!).Where(e => e.Id == CharacterStatController.LevelId))
+        {
+            Assert.Equal(0x40000010u, level.FontDid);
+            Assert.True(level.Outline);
+            Assert.NotNull(level.FontColor);
+            Assert.Equal(1f, level.FontColor!.Value.X, precision: 3);
+            Assert.Equal(0.949f, level.FontColor!.Value.Y, precision: 2);
+            Assert.Equal(0.498f, level.FontColor!.Value.Z, precision: 2);
+        }
+
+        foreach (var xpLabel in Flatten(tree!).Where(e => e.Id == CharacterStatController.XpNextLabelId))
+            Assert.Equal(0x40000000u, xpLabel.FontDid);
+        foreach (var xpValue in Flatten(tree!).Where(e => e.Id == CharacterStatController.XpNextValueId))
+            Assert.Equal(0x40000000u, xpValue.FontDid);
+    }
+
+    /// <summary>
+    /// The stat ListBox (<c>0x1000023D</c>) authors a five-entry template
+    /// list in LayoutDesc <c>0x21000045</c>: one shared icon+name+value data
+    /// row (<c>0x10000248</c>) plus four skill section-header captions
+    /// (<c>0x10000249..0x1000024C</c>). Pins the roster + the ListBox's own
+    /// authored scrollbar linkage.
+    /// </summary>
+    [InstalledDatFact]
+    public void StatListBox_AuthorsFiveRowTemplatesInSharedLayout()
+    {
+        using var dats = new DatCollection(DatDirectory, DatReaderWriter.Options.DatAccessType.Read);
+        ElementInfo? tree = LayoutImporter.ImportInfos(dats, 0x2100002Eu);
+        Assert.NotNull(tree);
+
+        // Duplicated once per Attributes-page/Skills-page chain, same as the
+        // header block — both copies are asserted identical.
+        var listBoxes = Flatten(tree!).Where(e => e.Id == CharacterStatController.ListBoxId).ToList();
+        Assert.Equal(2, listBoxes.Count);
+        uint[] expected =
+        {
+            0x10000248u, 0x10000249u, 0x1000024Au, 0x1000024Bu, 0x1000024Cu,
+        };
+        foreach (ElementInfo listBox in listBoxes)
+        {
+            Assert.Equal(CharacterStatController.ListScrollbarId, listBox.ScrollbarElementId);
+            Assert.Equal(5, listBox.TemplateList.Count);
+            foreach (uint id in expected)
+            {
+                Assert.Contains(
+                    listBox.TemplateList,
+                    t => t.TemplateLayoutId == 0x21000045u && t.TemplateElementId == id);
+            }
+        }
+    }
+
+    /// <summary>
+    /// The shared attribute/skill data-row template (<c>0x10000248</c> in
+    /// LayoutDesc <c>0x21000045</c>) — the icon/name/value geometry CT5
+    /// implements against. NOTE: this element is intentionally unreachable
+    /// via <see cref="LayoutImporter.ImportInfos(DatReaderWriter.IDatReaderWriter,uint)"/>'s
+    /// whole-layout overload (the <c>#375</c> same-layout template-list skip
+    /// filter) — the targeted single-root overload
+    /// (<c>ImportInfos(dats, layoutId, elementId)</c>) is required, the same
+    /// seam <c>UiTemplateListBox</c>'s <c>TemplateResolver</c> already uses.
+    /// </summary>
+    [InstalledDatFact]
+    public void AttributeRowTemplate_IconIsFlushLeftTwentyPixels_NameAndValueAreFixedColumns()
+    {
+        using var dats = new DatCollection(DatDirectory, DatReaderWriter.Options.DatAccessType.Read);
+        ElementInfo? row = LayoutImporter.ImportInfos(dats, 0x21000045u, 0x10000248u);
+        Assert.NotNull(row);
+
+        Assert.Equal(282f, row!.Width);
+        Assert.Equal(20f, row.Height);
+        Assert.Equal(0x06004CC2u, row.StateMedia["Normal"].File);
+        // Row-template Highlight sprite (0x06000F93) — CharacterStatController's
+        // current RowHighlightSprite private constant is 0x06001397, a
+        // divergence flagged (not fixed) by CT1; see the research doc's
+        // "Corrections to the plan" §3.
+        Assert.Equal(0x06000F93u, row.StateMedia["Highlight"].File);
+
+        ElementInfo icon = Assert.Single(row.Children, c => c.Id == 0x10000129u);
+        Assert.Equal(0f, icon.X);
+        Assert.Equal(0f, icon.Y);
+        Assert.Equal(20f, icon.Width);
+        Assert.Equal(20f, icon.Height);
+
+        ElementInfo name = Assert.Single(row.Children, c => c.Id == 0x1000012Au);
+        Assert.Equal(25f, name.X);
+        Assert.Equal(150f, name.Width);
+        Assert.Equal(HJustify.Left, name.HJustify);
+        Assert.Equal(0x40000001u, name.FontDid);
+
+        ElementInfo value = Assert.Single(row.Children, c => c.Id == 0x1000012Bu);
+        Assert.Equal(175f, value.X);
+        Assert.Equal(100f, value.Width);
+        Assert.Equal(HJustify.Right, value.HJustify);
+        Assert.Equal(0x40000001u, value.FontDid);
+
+        // Item 2: 7px gap between the value's right edge (275) and the row's
+        // own right edge (282) — the authored margin the owner reported.
+        Assert.Equal(7f, row.Width - (value.X + value.Width));
+    }
+
+    /// <summary>
+    /// The four skill section-header caption templates already match
+    /// <c>CharacterStatController</c>'s existing sprite constants exactly —
+    /// a regression guard, not a bug pin (unlike the data-row template
+    /// above).
+    /// </summary>
+    [InstalledDatFact]
+    public void SkillSectionHeaderTemplates_MatchExistingSpriteConstants()
+    {
+        using var dats = new DatCollection(DatDirectory, DatReaderWriter.Options.DatAccessType.Read);
+
+        (uint elementId, uint expectedSprite)[] headers =
+        {
+            (0x10000249u, 0x06000F90u), // SkillHeaderSpecializedSprite
+            (0x1000024Au, 0x06000F86u), // SkillHeaderTrainedSprite
+            (0x1000024Bu, 0x06000F98u), // SkillHeaderUntrainedSprite
+            (0x1000024Cu, 0x06000F89u), // SkillHeaderUnusableSprite
+        };
+        foreach (var (elementId, expectedSprite) in headers)
+        {
+            ElementInfo? header = LayoutImporter.ImportInfos(dats, 0x21000045u, elementId);
+            Assert.NotNull(header);
+            Assert.Equal(280f, header!.Width);
+            Assert.Equal(20f, header.Height);
+            Assert.Equal(expectedSprite, header.StateMedia[""].File);
+        }
+    }
+
+    /// <summary>
+    /// The Titles page (<c>gmCharacterTitleUI::PostInit @0x0049A610</c>)
+    /// element roster: display-title text <c>0x1000052F</c>, title ListBox
+    /// <c>0x10000532</c> (with its scrollbar linkage + row-template
+    /// reference), "Set as Display Title" button <c>0x10000535</c> (with the
+    /// authored Ghosted default state matching the ghost-when-current
+    /// contract).
+    /// </summary>
+    [InstalledDatFact]
+    public void TitlesPage_ElementRosterExists()
+    {
+        using var dats = new DatCollection(DatDirectory, DatReaderWriter.Options.DatAccessType.Read);
+        ElementInfo? tree = LayoutImporter.ImportInfos(dats, 0x2100002Eu);
+        Assert.NotNull(tree);
+
+        ElementInfo page = Assert.Single(Flatten(tree!), e => e.Id == 0x10000539u);
+        Assert.Equal(300f, page.Width);
+        Assert.Equal(575f, page.Height);
+
+        ElementInfo displayTitle = Assert.Single(page.Children, c => c.Id == 0x1000052Fu);
+        Assert.Equal(0x40000001u, displayTitle.FontDid);
+        Assert.Equal(HJustify.Center, displayTitle.HJustify);
+
+        ElementInfo listBox = Assert.Single(page.Children, c => c.Id == 0x10000532u);
+        Assert.Equal(5u, listBox.Type); // Type-5 ListBox
+        Assert.Equal(0x10000533u, listBox.ScrollbarElementId);
+        UiTemplateListEntry template = Assert.Single(listBox.TemplateList);
+        Assert.Equal(0x2100005Eu, template.TemplateLayoutId);
+        Assert.Equal(0x10000536u, template.TemplateElementId);
+
+        ElementInfo setDisplayButton = Assert.Single(page.Children, c => c.Id == 0x10000535u);
+        Assert.Equal(1u, setDisplayButton.Type); // Type-1 button
+        Assert.Equal(65, setDisplayButton.MinWidth);
+        Assert.Equal("Ghosted", setDisplayButton.DefaultStateName);
+    }
+
+    /// <summary>
+    /// The title row template (<c>0x10000536</c> in LayoutDesc
+    /// <c>0x2100005E</c>) — a single-line text row, no icon column, 24px
+    /// tall. Same targeted-root-overload requirement as the stat row
+    /// templates.
+    /// </summary>
+    [InstalledDatFact]
+    public void TitleRowTemplate_IsSingleLineTextRowWithNoIconColumn()
+    {
+        using var dats = new DatCollection(DatDirectory, DatReaderWriter.Options.DatAccessType.Read);
+        ElementInfo? row = LayoutImporter.ImportInfos(dats, 0x2100005Eu, 0x10000536u);
+        Assert.NotNull(row);
+
+        Assert.Equal(270f, row!.Width);
+        Assert.Equal(24f, row.Height);
+        // DirectState (the "" key), not a named "Normal" state.
+        Assert.Equal(0x06004CCAu, row.StateMedia[""].File);
+        Assert.Equal(0x06001AAFu, row.StateMedia["Highlight"].File);
+
+        ElementInfo text = Assert.Single(row.Children);
+        Assert.Equal(0x10000537u, text.Id);
+        Assert.Equal(270f, text.Width);
+        Assert.Equal(24f, text.Height);
+        Assert.Equal(HJustify.Left, text.HJustify);
+        Assert.Equal(6, text.MarginLeft);
+        Assert.Equal(6, text.MarginRight);
+        Assert.Equal(0x40000001u, text.FontDid);
+    }
+
+    /// <summary>
+    /// Item 3/7 ground truth: the character window's imported root
+    /// (<c>0x10000227</c>, the Type-8 TabControl <c>ImportInfos</c> returns
+    /// and <c>RetailUiRuntime.MountCharacter</c> mounts) authors NO
+    /// MinWidth/MinHeight/MaxWidth/MaxHeight — unlike e.g. the side-vitals
+    /// window (LayoutDesc <c>0x21000075</c>) whose root DOES author
+    /// 0x3C..0x3F directly. Pinned so CT6 doesn't waste a cycle assuming a
+    /// simple "read the DAT property" fix is available for this window;
+    /// see the research doc's "Corrections to the plan" §1.
+    /// </summary>
+    [InstalledDatFact]
+    public void CharacterWindowRoot_AuthorsNoSizeConstraints()
+    {
+        using var dats = new DatCollection(DatDirectory, DatReaderWriter.Options.DatAccessType.Read);
+        ElementInfo? tree = LayoutImporter.ImportInfos(dats, 0x2100002Eu);
+        Assert.NotNull(tree);
+        Assert.Equal(0x10000227u, tree!.Id);
+        Assert.Equal(8u, tree.Type); // Type-8 TabControl
+
+        Assert.Null(tree.MinWidth);
+        Assert.Null(tree.MinHeight);
+        Assert.Null(tree.MaxWidth);
+        Assert.Null(tree.MaxHeight);
+    }
+
+    /// <summary>
+    /// Comparison point for the pin above: the chat window's root DOES
+    /// author explicit size constraints, because unlike the character
+    /// panel's content-only layout, <c>0x2100006F</c>'s root IS a
+    /// self-contained window element (its own dragbar/border/resize-grip
+    /// children).
+    /// </summary>
+    [InstalledDatFact]
+    public void ChatWindowRoot_AuthorsExplicitSizeConstraints()
+    {
+        using var dats = new DatCollection(DatDirectory, DatReaderWriter.Options.DatAccessType.Read);
+        ElementInfo? tree = LayoutImporter.ImportInfos(dats, 0x2100006Fu);
+        Assert.NotNull(tree);
+        Assert.Equal(0x10000600u, tree!.Id);
+
+        Assert.Equal(300, tree.MinWidth);
+        Assert.Equal(100, tree.MinHeight);
+        Assert.Equal(2000, tree.MaxWidth);
+        Assert.Equal(2000, tree.MaxHeight);
+    }
+
+    /// <summary>
+    /// The title-string table chain
+    /// (<c>CharacterTitleTable::GetCharacterTitleFromID @0x005c6ed0</c>):
+    /// title id → <c>EnumMapper(0x22000041)</c> canonical name →
+    /// <c>compute_str_hash</c> → <c>StringTable(0x2300000E)</c> localized
+    /// text. Both DIDs are resolved via the two-level
+    /// <c>DBObj::GetDIDByEnum</c> master-map chain (master map
+    /// <c>0x25000000</c> → category map → target DID) — see the research
+    /// doc §5 for the full derivation. Verified end to end against ACE's
+    /// <c>CharacterTitle.WarMage = 13</c>.
+    /// </summary>
+    [InstalledDatFact]
+    public void TitleStringTable_ResolvesWarMageEndToEnd()
+    {
+        using var dats = new DatCollection(DatDirectory, DatReaderWriter.Options.DatAccessType.Read);
+
+        bool gotMapper = dats.Portal.TryGet<DatReaderWriter.DBObjs.EnumMapper>(
+            0x22000041u, out var titleEnumMapper);
+        Assert.True(gotMapper);
+        Assert.NotNull(titleEnumMapper);
+        string raw = titleEnumMapper!.IdToStringMap[13u].ToString();
+        Assert.Equal("ID_CharacterTitle_War_Mage", raw);
+
+        uint hash = DatStringResolver.ComputeHash(raw);
+        Assert.Equal(0x0543AF05u, hash);
+
+        var resolver = new DatStringResolver(dats);
+        string? resolved = resolver.Resolve(0x2300000Eu, hash);
+        Assert.Equal("War Mage", resolved);
+    }
+}