Skip to content
Version 2.32.0
↓ Get the launcher

WindowSpec record

Immutable declaration of a plugin window’s identity, initial geometry, and chrome options. Passed to Register to create the window.

public record WindowSpec : IRenderGated
name description
Anchor { get; set; } Anchor for the initial placement of DefaultRect on the (possibly scaled) window canvas. Defaults to TopLeft = legacy absolute top-left. Use Center etc. to center/corner-anchor without computing the UI scale yourself; DefaultRect.X/Y then act as a canvas-unit offset from the anchor. A user’s saved drag still overrides this.
AutoSizeWidth { get; set; } Content-size the window WIDTH to its body instead of fixing it to DefaultRect.Width. Only safe for windows without wrapping text (e.g. the launcher’s fixed-width icon tiles) — the in-world clip bug that forced fixed width was a wrapping-text problem the launcher does not have. Defaults false.
BackgroundOpacity { get; set; } Borderless windows only: poll-diffed black background opacity (0 = transparent, 1 = fully black). Applied to the root’s existing click-blocker Image so the background fills the entire window rect and expands when the user resizes height — no separate child GO needed. Null = no background (default).
Category { get; set; } Logical category that determines which group this window appears in within the layout editor.
Closable { get; set; } When true the chrome draws a ✕ close glyph that hides the window. Defaults false (plugin windows manage their own visibility). Independent of Draggable so a window can be draggable without a close button (e.g. the Settings hub).
DefaultRect { get; set; } Initial position and size applied on first run (before user adjustments are persisted).
DismissOnOutsideClick { get; set; } When true the framework auto-hides this window on Escape or a mouse press outside its rect — the click-away dismiss a cursor popup / context menu wants. The dismiss invokes the registration’s OnClose (wire it to SetVisible(false)); with no OnClose the flag is inert. Handled on the per-render-frame interaction ticker, NOT the throttled framework tick, so it never misses a one-frame click/key edge (a press lasting one rendered frame would be missed by a plugin polling input from its throttled OnUpdate).
DisplayTitle { get; } The title the window chrome DISPLAYS: TitleProvider if set, otherwise Title. Invokes the provider (so it throws if the provider does) — read it only where the window is being drawn.
Draggable { get; set; } When true the window is a movable dialog: drag-by-title-bar (the post-drag rect is committed + persisted) and excluded from the Shift+` Layout editor (it owns its own position). When false the window is positioned via the Layout editor and any title-bar drag is discarded. Defaults false. Settings windows + opt-in plugin panels (e.g. StatInspector settings) set this true.
EditModeDragOnly { get; set; } When true the chrome draws a bottom-right ↘ resize grip; dragging it changes the window size (clamped to MinWidth/MinHeight .. MaxWidth/MaxHeight), and the new size persists alongside the position. The window’s vertical content-fit is disabled (fixed height); a ScrollElement in the body fills the freed space. Defaults false. The CombatMeter list uses this.
FixedHeight { get; set; } Pin the window HEIGHT to DefaultRect.Height instead of fitting it to the content (GlassMenu chrome; ignored when Resizable, which already fixes the size). The vertical ContentSizeFitter is off, so a body whose preferred height exceeds the pinned height can never grow the window: uGUI squeezes the body toward its MIN height instead (a VirtualList / ScrollElement viewport has min 0, so lists give way first). For a tabbed window that must keep one size on every tab (the Settings hub). Default false = content-fit, as before. Init-only → binary-safe (no plugin rebuild).
FrameOpacity { get; set; } GlassMenu windows only: per-window override of the frame (background) opacity, polled live like the global theme setting. Return a value in [0.3, 1] to override, or null to follow the framework’s Themes → Window Opacity (IChromeStyle.WindowOpacity). Only the frame background fades; content stays opaque. Null delegate (default) = always follow the framework.
Id { get; set; } Stable string id, unique per plugin. Used to persist position and hotkey binding.
IsolateCanvas { get; set; } Opt-in: render this window on its OWN nested uGUI Canvas (a batching boundary) instead of sharing the single overlay canvas with every other window. Changes inside this window (notably a ScrollRect moving its content every frame) then rebuild only THIS window’s batch, never dirtying or rebatching the overlay or sibling windows — the fix for a scroll/animation FPS drop that scales with how many other windows are open. Unlike OverrideSortingOrder this does NOT pin an absolute sortingOrder and does NOT opt out of sibling-order z: the nested Canvas uses overrideSorting=false, so BringToFront / ReorderWindows still work. Default false = unchanged (shared canvas). Added as an init property (NOT a ctor param) so WindowSpec stays source + binary compatible with already-compiled plugins.
MaxHeight { get; set; } Maximum allowed window height in pixels when Resizable is true.
MaxWidth { get; set; } Maximum allowed window width in pixels when Resizable is true.
MinHeight { get; set; } Minimum allowed window height in pixels when Resizable is true.
MinWidth { get; set; } Minimum allowed window width in pixels when Resizable is true.
OverrideSortingOrder { get; set; } When set, the window renders on its OWN nested Canvas with overrideSorting=true at this absolute sortingOrder, instead of taking its z from sibling order within the shared Stellar window canvas. Use it to lift one window above overlays drawn on a HIGHER canvas than the window layer — e.g. the layout editor’s edit chrome (32758) — while keeping it below the top input blocker (32760). A GraphicRaycaster is added on the nested canvas alongside, so the window stays hit-testable at the correct order (a nested canvas is otherwise skipped by the parent raycaster). Null (default) = normal sibling-z. The override child simply opts ITSELF out of sibling-order z; every other window’s z-order is untouched.
Passive { get; set; } Borderless windows only: a purely visual layer. No content padding (the content starts at the window’s top-left corner and fills its rect exactly) and no click blocker, so presses and pointer-over-UI checks fall through to the game and to every window behind it. For full-screen guides and overlays that must never take input (e.g. a photo frame guide). Default false.
Prebuild { get; set; } Build this window ahead of its first open, at moments where a freeze doesn’t matter, so the first open is a plain re-show instead of a 100-400 ms build. Meant for big windows the player opens by hand (hubs, confirm dialogs, chat, meters) that start hidden. The window stays hidden throughout (IsShown false), never takes clicks or hover, and its z-order is untouched. Two stages, both framework-driven:
PrebuildSignature { get; set; } With Prebuild: a CHEAP hash of what the window would show (row counts, selected tab, ids of the listed things — not every changing number). Sampled about twice a second while the window is hidden and filled; when it changes, the fill re-runs off-screen (behind a loading screen if one is up, else during play outside combat), so content that grew while hidden doesn’t rebuild inside the open. Null (default) = filled once per world entry. A throwing signature reads as “unchanged”. Init-only → binary-safe. Added in 2.30.0.
Resizable { get; set; } When true the chrome draws a resize grip; dragging it changes the window size (clamped to Min/Max bounds).
ShouldRender { get; set; } The single source of visibility truth (hide = !ShouldRender(), evaluated each apply ~10 Hz). Compiler-required: every WindowSpec MUST set it or the build fails. Read whatever you want — Phase, UiState, your own state — via the plugin’s captured services. Use () => true for always-on chrome, () => _services.ClientState.Phase == GamePhase.World for a gameplay window.
ShowTitleBar { get; set; } GlassMenu only: draw the top title bar. Defaults true. Set false for windows that self-compose their own header inside the body (the launcher, whose header is top in Full/vertical but a LEFT strip in horizontal — a single fixed top bar can’t express both). With no title bar the whole frame becomes the drag handle (if Draggable), and the body must supply its own close affordance.
SlotIndependentLayout { get; set; } When true this window’s position and visibility persist in a single resolution-keyed bucket INDEPENDENT of the active layout slot: switching layout slots never moves or re-hides it, and its dragged position is remembered per-resolution across the whole session rather than per slot. Used by framework chrome like the layout-edit toolbar, whose own placement must be global (one position across all slots) because it is not part of any saved player arrangement. Null/false (default) = normal per-slot layout. Init-only → binary-safe (no plugin rebuild).
StartVisible { get; set; } Whether the window is visible on first run (before user toggles via hotkey).
Style { get; set; } Visual chrome style applied to the window frame.
Surface { get; set; } Which render surface the window’s Text / Bar (Default style) / Pill leaves use. Defaults to Menu = the window theme chrome (unchanged — every existing window keeps rendering exactly as before). Set HudOverlay to reproduce the borderless HUD look for those leaves: shadowed text over the world, rounded HP-bar chrome, and a transparent pill chip — byte-identical to the native HUD renderer, so a HUD-path plugin can migrate onto the window path with pixel-exact fidelity. Only those three leaf types are affected; all other widgets render identically either way. The positional constructor is unchanged, so this is non-breaking.
Title { get; set; } Display title shown in the title bar and Settings layout editor.
TitleProvider { get; set; } Optional live-localized DISPLAY title for the window chrome, mirroring TitleProvider: evaluated when the window is built (which happens only once it is first shown) and again on a theme/language change, never per frame. null (the default) shows Title. Set it to () => services.Localization.T("your.title.key") so the title is read in the player’s language without resolving it at registration time. Title stays the fallback: the window chrome falls back to Title if the provider throws (and logs it once). Identity is Id, never the title.
Topmost { get; set; } Pin the window “always on top”: it draws above every non-topmost Stellar window, whatever was opened or brought to the front later (only click-away popups, the dropdown list and the layout-edit toolbar sit higher). Among topmost windows the last opened / fronted is on top. Meant for SMALL pinned overlays and alerts — not for normal tool windows, which should simply stack by what the user used last. Hit-testing follows the draw order, so a topmost window blocks clicks to windows behind it (unless it is Passive), and ShouldRender still hides it. Default false. Toggle it at runtime with IWindowTopmost (control.SetTopmost(bool)). Added in 2.30.0.
ZOrder { get; set; } Explicit draw-order among Stellar windows: HIGHER draws on top. Default 0. The framework stacks windows (bottom → top) by: Topmost windows above all others, then ZOrder, then the layer (HUD windows below Tools/Debug windows; a HUD window brought to the front joins the upper layer until it is hidden), then the most recently opened / brought-to-front window on top. So a plugin that sets this controls where its window sits relative to others regardless of load/mount order; one that leaves it 0 stacks by use. Click-away (DismissOnOutsideClick) popups always render above all of these.