acdream/docs/research/2026-08-13-retail-ui-display-change.md

Retail UI behavior on display-resolution change (research for #390)

Date: 2026-08-13 Oracle: docs/research/named-retail/acclient_2013_pseudo_c.txt (Sept 2013 EoR build, PDB-named), cross-checked against the raw PDB-paired binary (C:\Users\erikn\Downloads\acclient.exe, v11.4186) where the BN export lacked bodies. All addresses are the 2013 build's VAs.

Question: what does the retail client do to its UI windows when the display resolution changes, so floating windows never end up stranded off-screen? (acdream's floating retail-UI windows keep absolute pixel positions across resolution changes; shrinking strands them — user gate report 2026-08-13.)

---

Executive summary

Retail has three cooperating mechanisms, and all three matter:

1. A per-element re-anchoring cascade that runs on every parent resize. UIElement::ResizeTo iterates its children and calls UIElement::UpdateForParentSizeChange on each; that function recomputes the child's box from its authored ElementDesc position, its four edge-anchor modes (m_leftEdge/m_rightEdge/m_topEdge/m_bottomEdge), and the delta between the authored reference resolution stored in the LayoutDesc (LayoutDesc::m_displayWidth/m_displayHeight) and the actual display size — then applies the result through the element's virtual MoveTo + ResizeTo.
2. A clamp-to-parent rule baked into every floating window's MoveTo override: x = max(0, min(x, parentW - selfW)), y = max(0, min(y, parentH - selfH)). Because the cascade above ends in an unconditional virtual MoveTo, the clamp runs for every floating window on every resolution change — even when nothing else would have moved it. This is the mechanism that un-strands windows on shrink.
3. Per-resolution layout persistence: a plain-text auto-layout file keyed by character + world + resolution (UI-<char>-<world>-<W>-<H>.txt), reloaded automatically after every resolution change via a dedicated global UI message (0xE), plus a server-side fallback (PlayerModule "chat window options") applied through the same clamping MoveTo.

There is no proportional rescaling of window positions and no reset-to-default on display change (defaults only apply when an element's authored anchors say so). Positions persist per-resolution; the clamp is the safety net.

---

1. Trigger paths into a resolution change

Path	Function	Address	Notes
In-game Options change	Render::UpdateFromPreferences	0x0054D850	Diffs Device::m_DisplayPrefs.Resolution/FullScreen/RefreshRate/SyncToRefresh/Antialiasing against Current_Display_* statics; any diff → Device::ChangePresentation() at 0x0054DA29.
Console command	Device::ConsoleCommand_ForceDisplayResolution	0x0043A830	ForceDisplayResolution [w h] → Device::ForceDisplayResolution (0x0043A750) → ChangePresentation when the size actually differs.
Login/char-select ↔ gameplay	gmGamePlayUI::gmGamePlayUI / ~gmGamePlayUI	0x004EA010 / 0x004EA2A0	Pre-gameplay screens run force-800x600 (ForceDisplayResolution(1, 0x320, 0x258)); the gameplay ctor un-forces (0x004EA093) → switch to the user's preferred resolution; the dtor re-forces (0x004EA353).
Device lost (alt-tab etc.)	Render::CheckForLostDevice	0x0054E890	Same-resolution Render::RestartRenderingSystem(); runs the UI refresh cascade below but does not broadcast 0xE (no layout reload).

2. Device::ChangePresentation (0x0043A2D0) — the device-side sequence

1. Device::LoadDisplayPreferences — read the desired presentation (the Display.Resolution preference packs W/H into one dword: W = res >> 16, H = res & 0xFFFF, see 0x00439070).
2. Strip/refresh window styles (SetWindowLongA, SetWindowPos).
3. Render::RestartRenderingSystem(presentation, config) (0x0054D6B0): Render::RestartDevice + GraphicsResource::RestoreLostResources() + fire every registered RGR callback ("restore graphics resources", Render::LinkRGRCallback 0x0054F000). The UI's callback is described in §3.
4. Compute the new OS window rect (windowed mode): client size + dialog-frame/caption metrics (GetSystemMetrics), centered on the previous window rect (or the screen), then clamped into the desktop work area (SystemParametersInfoA(SPI_GETWORKAREA)) — left/top-priority clamp, 0x0043A459..0x0043A4A9. SetWindowPos applies it.
5. On success: UIElementManager::BroadcastGlobalMessage(0xE, 0) (0x0043A4E6). On failure: fatal error dialog + exit(1).

Note the ordering: the UI refresh cascade (§3) runs inside step 3; the 0xE broadcast (§5's layout reload) happens after it.

3. The UI refresh cascade — UIElementManager::RefreshEvent (0x0045C530)

UIElementManager::Init (0x0045EE10) registers RefreshEvent_g as an RGR callback at 0x0045EEB9. When the device restarts:

1. BroadcastGlobalMessage(5, 0) — no registrant of global message 5 was found in this build (see UNKNOWNs).
2. m_pRootElement->vtable->ResizeTo(GetDisplayWidth(), GetDisplayHeight()) — the manager's root ("hollow element", a plain full-screen UIElement created at display size by CreateHollowElement 0x0045D0E0) is resized to the new display size.
3. UIRegion::ForceUpdate(root, 7), DrawDirtyRegions, cursor re-set.

3a. UIElement::ResizeTo (0x00463C30) cascades to children

After clamping the requested size against the element's min/max attributes (attr ids 0x3C..0x3F) and updating its own box, if the size actually changed it walks m_children and calls UIElement::UpdateForParentSizeChange(child) (loop at 0x00463E25..0x00463E52). All UI pages are under the manager root (mouse hit-testing recurses from m_pRootElement), so a display change reflows the whole tree.

UIRegion::MoveTo (0x0069F830) and UIRegion::ResizeTo (0x0069F8C0) themselves are pure box math — x0/y0/x1/y1 updates plus dirty-region invalidation, no children, no clamping (verified by disassembling the PDB-paired binary; the BN export lacks these two bodies).

3b. UIElement::UpdateForParentSizeChange (0x00462640) — the actual math

Inputs per element:

• GetOriginalPosition(this) — the authored ElementDesc box (origX0, origY0, origX1, origY1) + authored z-level.
• The old reference frame:
  • Root-level element (no parent, or __inner23 bit 21 set — set by SetIsRootElement): the LayoutDesc's authored reference resolution — old frame = (0,0)..(m_layout->m_displayWidth - 1, m_layout->m_displayHeight - 1). Retail .uil LayoutDescs embed the resolution they were authored at (fields at LayoutDesc+0x30/+0x34, serialized at 0x0069A4C3/0x0069A4EB).
  • Otherwise: the parent's original box (GetOriginalPosition(parent)).
• The new reference frame:
  • Root-level: (0,0)..(displayW-1, displayH-1) from the live RenderDevice.
  • Otherwise: the parent's current box (GetCurrentPosition(parent)).

Derived:

deltaW = (newFrameWidth  - oldFrameWidth)        // ebx_6 at 0x00462766
deltaH = (newFrameHeight - oldFrameHeight)       // ecx_12 at 0x00462762
scale  = newFrameWidth / oldFrameWidth           // float, 0x00462794 (mode-4 only)

Per-edge application (values are the raw m_desc.m_leftEdge etc. — verbatim retail field names from the PDB):

edge value	left/top coordinate	right/bottom coordinate
0	authored; but if the element already has a size: keep the CURRENT runtime coordinate (0x00462959..) — this is the "free-floating window" mode	same rule (keep current x1/y1)
1	authored (left/top-anchored)	orig + delta (right/bottom-anchored — stretches with the frame)
2	orig + delta (right/bottom-anchored)	authored
3	centered: (newSize>>1) - (origSize>>1)	centered: (newSize>>1) + (origSize>>1) - 1
4	proportional: ftol(scale * ...) (exact float expr elided by BN)	proportional

Finally — and this is the load-bearing part:

this->vtable->MoveTo(newX0, newY0);                              // 0x00462998 — VIRTUAL
this->vtable->ResizeTo(newX1-newX0+1, newY1-newY0+1);            // 0x004629A1 — VIRTUAL

MoveTo is called unconditionally — even for a free-floating (all-edges-0) window whose coordinates come out unchanged. The virtual dispatch lands in the floating-window overrides below, so the clamp runs for every floating window on every display change.

4. The clamp rule — floating-window MoveTo overrides

Every "floaty" window class overrides MoveTo with the same exact math:

if (GetParent() != null) {
    if (x > parentWidth  - selfWidth)  x = parentWidth  - selfWidth;
    if (x < 0)                         x = 0;
    if (y > parentHeight - selfHeight) y = parentHeight - selfHeight;
    if (y < 0)                         y = 0;
}
UIElement::MoveTo(x, y);
if (m_eWindowID != 0 && PlayerSystem exists)
    write clamped X/Y into PlayerModule chat-window options   // see §5b

Order of the two clamps means top-left wins when the window is larger than the parent (x first clamped possibly negative, then floored to 0).

Clamping classes (all confirmed in the pseudo-C):

class	MoveTo addr
gmFloatyToolbarUI	0x004CFE80
gmFloatyPowerBarUI	0x004D15D0
gmFloatyPanelUI (the tabbed side panel host)	0x004D20B0
gmFloatyMainChatUI (main chat when floating)	0x004D2D10
gmFloatyIndicatorsUI	0x004D38C0
gmFloatyExaminationUI	0x004D45E0
gmFloatyCombatPanelUI	0x004D5190
gmSmartBoxUI (the 3D viewport window)	0x004D67E0
gmRadarUI	0x004D81A0

NOT clamping (verified):

• gmMainChatUI::MoveTo (0x004CCCC0) — docked main chat; persists dock offsets into element attributes 0x54/0x55, no clamp.
• gmFloatyChatUI::MoveTo (0x004CE840) — the extra floating chat windows (FCH1–FCH4 in the layout file): persists X/Y to PlayerModule but does not clamp. Retail's floating chat windows 1–4 genuinely can sit off-screen; only the auto-layout file or a re-anchor can recover them. (Retail quirk — see "what acdream should do".)
• Base UIElement::MoveTo (0x004633E0): no positional clamp at all.
• UIElement::ResizeTo clamps only against min/max size attributes (0x3C..0x3F), never against the screen.

The same overrides are the drag path (title-bar drag ends in the virtual MoveTo), so interactive dragging obeys the same bounds — drag clamping and display-change clamping are literally the same code.

5. Per-resolution layout persistence

5a. The screen-layout file (gmGamePlayUI)

gmGamePlayUI is the only registrant of global message 0xE (RegisterForGlobalMessage(this, 0xE) at 0x004EA0B1). Its handler (ListenToGlobalMessage 0x004EB5A0):

case 0xE:  if (!m_endingSession) LoadScreenLayout("#auto");

CreateScreenLayoutPath (0x004EA690) builds the file path in the directory of the user-preferences file (PSUtils::get_directory(UserPreferences::sm_strDefaultFile)):

name argument	format (string addr)	result
"#auto" (0x007C2A3C)	"%sUI-%s-%s-%d-%d.txt" (0x007C2A24)	UI-<charName>-<worldName>-<W>-<H>.txt where W/H = UIRegion::GetWidth/GetHeight(m_pGameplayUI) — the gameplay page's CURRENT size == the display resolution. Layouts are keyed per character + world + resolution.
empty	"%sUI-Default.txt" (0x007C2A10)	shared default file
anything else	"%s%s.txt" (0x007C2A04)	named file (@saveui <name>)

SaveScreenLayout (0x004EAD50) writes one text line per movable window: <TAG> X:%d Y: %d W: %d H: %d (screen-space X0/Y0 + width/height), for exactly 16 elements. LoadScreenLayout (0x004EA8F0) reads lines with sscanf("%s X:%d Y: %d W: %d H: %d") (0x007C2AC4), maps the 6-char tag to an element id, then applies ResizeTo(W,H) first, MoveTo(X,Y) second (0x004EAC8E) — both virtual, so the §4 clamp applies to everything loaded. If the file does not exist the function returns 0 and touches nothing.

Tags (strings at 0x007C2A44..0x007C2ABC): <SBOX> <CHAT> <FCH1>..<FCH4> <EXAM> <VITS> <SVIT> <ENVP> <PANS> <TBAR> <INDI> <PBAR> <COMB> <RADA>. Element ids in save order: 0x1000049A (smartbox), 0x10000601 (main chat), 0x10000505/0x1000050E/0x1000050F/0x10000510 (floaty chat 1–4), 0x100005F7, 0x100005FA (stacked vitals), 0x100006D5 (side-by-side vitals), 0x100005FD, 0x100005FF, 0x10000603, 0x10000611, 0x10000613, 0x100006B5, 0x100006D2 (radar).

Load triggers:

• RecvNotice_PlayerDescReceived (0x004EB660) — login: LoadScreenLayout("#auto"); the boolean result is stored in CPlayerSystem::m_layoutFromFile.
• Global message 0xE — every resolution change (this is the "layout follows the resolution" behavior the @saveautoui help text describes).
• @loadui [<name>] / @loadautoui (handlers ClientCommunicationSystem::DoLoadUI 0x00570150; saveautoui/loadautoui registered at 0x00584FBD/0x00585029).

Save triggers: only @saveui [<name>] (DoSaveUI 0x0056FFF0 → CM_UI::SendNotice_SaveUI → gmGamePlayUI::RecvNotice_SaveUI 0x004EB600) and @saveautoui (passes "#auto"). Retail never auto-saves the layout file — not on exit, not on drag. Ambient persistence is PlayerModule's job (§5b).

Help text (verbatim, data 0x007DCB90): "@saveautoui - Stores the current layout to a character and resolution specific file. This layout will automatically be used when the resolution changes for this character to the current size."

5b. Server-side fallback — PlayerModule chat-window options

Every floaty window with a nonzero m_eWindowID writes its (clamped) geometry into the PlayerModule on every move/resize via PlayerModule::SetChatWindowOption:

property	id
X	0x10000086
Y	0x10000087
W	0x10000088
H	0x10000089

This rides the PlayerModule blob (the same 0x01A1 save-path Campaign OP ported). On login / player-option notices, each floaty's UpdateFromPlayerModule (e.g. gmFloatyVitalsUI 0x004CF140, called from the tail of each floaty's setup and from notice 0x4DD1F0 handlers) applies the stored geometry — but only when CPlayerSystem::m_layoutFromFile == 0 (the auto-layout file wins when it exists) — again via the virtual, clamping MoveTo/ResizeTo.

So the restore priority is: per-resolution auto file > PlayerModule blob > authored LayoutDesc defaults, and every path funnels through the clamp.

6. So what exactly happens to a stranded window?

Scenario: 1600x1200 → 1024x768, window at (1400, 900).

1. ChangePresentation restarts the device; RefreshEvent resizes the manager root to 1024x768; UIElement::ResizeTo cascades UpdateForParentSizeChange down the tree.
2. The gameplay page (a root element) re-derives its box from its authored anchors against (authored LayoutDesc resolution → 1024x768) and shrinks; its own ResizeTo cascades to its children — the floating windows.
3. Each floating window's anchors are typically "free" (edge mode 0 → keep current coordinates), so the re-derivation yields its old (1400, 900) — but the result is applied through the window's clamping MoveTo, which pins it to (1024 - w, 768 - h). Clamp on display-change broadcast, not on load, and not a reset to default. The clamped position is immediately written back to PlayerModule.
4. Then the 0xE broadcast fires and, if UI-<char>-<world>-1024-768.txt exists, the user's saved 1024x768 layout overrides the clamped positions (ResizeTo before MoveTo, both clamped again).
5. Exception: the floating chat windows FCH1–FCH4 (gmFloatyChatUI) skip the clamp and genuinely can stay stranded in retail.

No file, no PlayerModule entry → the window keeps its authored-anchor-derived position, clamped. There is no proportional reposition of free-floating windows (mode 4 exists in the anchor system but retail's floating windows don't use it — they'd move on every change otherwise).

7. What acdream's port should do (mechanism only — no code here)

1. Keep per-resolution keying in RetailWindowLayoutPersistence — retail keys the auto layout by character + world + resolution. If we key only by resolution, that is a (small) divergence worth a register row; retail's key includes character and world.
2. Port the clamp into the floating-window move seam (the equivalent of the MoveTo override): x = max(0, min(x, parentW - selfW)), y likewise, top-left priority, applied on every programmatic or interactive move — restore-from-disk, restore-from-server, drag, and display-change reflow must all funnel through it.
3. On display change, run the reflow then the reload, in that order: (a) resize the UI root to the new display size and propagate a parent-size-change pass that ends in the clamping move for every floating window; (b) then load the per-resolution saved layout if one exists and apply it size-first, position-second, through the same clamping move.
4. Do not reset to authored defaults on display change and do not scale positions proportionally — retail does neither for free-floating windows.
5. Apply-order detail worth copying: retail applies ResizeTo(W,H) before MoveTo(X,Y) when restoring a window, so the clamp evaluates against the restored size, not the stale one.
6. Decision point (flag for the user): retail's floating chat windows FCH1–FCH4 do NOT clamp and can be stranded. Matching that exactly is retail-faithful; clamping them too is a deliberate quality divergence that needs a register row.
7. The anchor system (edge modes + LayoutDesc authored reference resolution) is the general mechanism that keeps docked/authored HUD elements correct across resolutions. If acdream's importer currently bakes absolute pixel positions at import time, the full fix for authored (non-floating) elements is the UpdateForParentSizeChange equivalent — worth its own slice; the floating-window stranding fix only needs items 1–5.

8. UNKNOWNs / ambiguities

• Global message 5 (broadcast by RefreshEvent): no RegisterForGlobalMessage(_, 5) site found; presumed a no-op in the 2013 build. (Message ids seen in use: 1 keypress, 3 per-frame UseTime, 0xB, 0xC, 0xD = UI-lock toggled (@lockui → UpdateLockedStatus), 0xE display-changed.)
• Exact tag↔element-id mapping for the ten middle entries of the layout file: the per-tag format-string operands are BN-mislabeled vtable-relative constants. SBOX, CHAT, FCH1–4 are confirmed by adjacent data; RADA=0x100006D2 (radar), VITS=0x100005FA (stacked vitals) and SVIT=0x100006D5 (side-by-side vitals) are high-confidence from SetupChildren member names; TBAR/PBAR/PANS/INDI/EXAM/COMB/ENVP assignments to 0x100005F7/0x100005FD/0x100005FF/0x10000603/0x10000611/0x10000613/0x100006B5 are inferred from class names, not proven.
• Mode-4 (proportional) exact float expression in UpdateForParentSizeChange: BN elided the x87 sequence (_ftol2 with prior float state). The scale factor newFrameW/oldFrameW is visible; whether Y uses an independent Y-scale was not recoverable from the export (almost certainly yes by symmetry).
• __inner23 bit 21 ("use display frame instead of parent frame" in UpdateForParentSizeChange) is inferred to be the SetIsRootElement flag; the bit arithmetic is consistent but the setter's exact bit position was not independently confirmed.
• UIElement::SetSaveLocation/SetSaveSize (LayoutDesc attrs 0x12/0x13, setters 0x0045F930/0x0045F950 → __inner23 bits 4/5): no named consumer found; presumed vestigial or consumed by unlabeled code. They are NOT the persistence mechanism — that is the hardcoded 16-window list + PlayerModule.
• @saveautoui handler passing "#auto" is inferred from the #auto string, the DoSaveAutoUI neighborhood (0x005702C5..0x005702FA) and the help text; the exact call site line was not read end-to-end.
• The order of %s args (char vs world) in UI-%s-%s-%d-%d.txt was not provable from the BN export's local-variable listing; both names and both dimensions are in the filename, which is what matters for the port.

9. Key address appendix

Function	Address
Device::ForceDisplayResolution	0x0043A750
Device::ChangePresentation	0x0043A2D0 (0xE broadcast at 0x0043A4E6; work-area clamp 0x0043A459)
Render::UpdateFromPreferences	0x0054D850 (→ ChangePresentation 0x0054DA29)
Render::RestartRenderingSystem	0x0054D6B0 / wrapper 0x0054D710
Render::CheckForLostDevice	0x0054E890
Render::LinkRGRCallback	0x0054F000
UIElementManager::Init	0x0045EE10 (RGR hook 0x0045EEB9)
UIElementManager::RefreshEvent	0x0045C530
UIElementManager::CreateHollowElement	0x0045D0E0
UIElement::UpdateForParentSizeChange	0x00462640
UIElement::MoveTo / ResizeTo	0x004633E0 / 0x00463C30 (child cascade 0x00463E25)
UIElement::SetParent (also triggers re-anchor)	0x00462A50
UIRegion::MoveTo / ResizeTo (box math only; from binary disasm)	0x0069F830 / 0x0069F8C0
gmGamePlayUI ctor / dtor	0x004EA010 / 0x004EA2A0
gmGamePlayUI::ListenToGlobalMessage	0x004EB5A0
gmGamePlayUI::CreateScreenLayoutPath	0x004EA690
gmGamePlayUI::LoadScreenLayout	0x004EA8F0 (apply site 0x004EAC8E)
gmGamePlayUI::SaveScreenLayout	0x004EAD50
gmGamePlayUI::RecvNotice_PlayerDescReceived (m_layoutFromFile)	0x004EB660
ClientCommunicationSystem::DoSaveUI / DoLoadUI	0x0056FFF0 / 0x00570150
Clamping MoveTo overrides	see table in §4
gmFloatyVitalsUI::UpdateFromPlayerModule (restore pattern)	0x004CF140
Path/tag/format strings	0x007C2A04..0x007C2CC0
@saveautoui help text	0x007DCB90