SparrohUILib

Shared UI library for Sparroh Mycopunk mods. One theme, one set of widgets, resolution-aware layout.

Features

• Theme system — Mycopunk-inspired teal/slate surfaces with bioluminescent accents

• Resolution scaling — Reference 1920×1080; scales cleanly across aspect ratios via CanvasScaler + UITheme.Scale

• HUD builder — Single- and multi-line HUD text under the player reticle (normalized anchors); respects vanilla Hide HUD

• Widgets — Text, Button, Toggle, InputField, Panel, ScrollView, Separator, Dropdown, Slider, ProgressBar, Tabs, Tooltip

• Windows & dialogs — Overlay windows (per-window canvas), confirm/alert dialogs

• Rich text helpers — Label: value unit formatting with colored values

Install

Thunderstore / r2modman: install Sparroh-SparrohUILib as a dependency of your mod.

Manual: place SparrohUILib.dll in BepInEx/plugins/.

Consumer setup

csproj

<Reference Include="SparrohUILib">
  <HintPath>..\SparrohUILib\bin\Release\net48\SparrohUILib.dll</HintPath>
</Reference>

Plugin

[BepInDependency("sparroh.uilibrary")]
[BepInPlugin(...)]
public class MyPlugin : BaseUnityPlugin { }

thunderstore.toml

[package.dependencies]
BepInEx-BepInExPack_Mycopunk = "5.4.2403"
Sparroh-SparrohUILib = "1.0.0"

Quick examples

using Sparroh.UI;

// HUD (Altimeter-style) — rebuild when the handle dies after quit-to-menu
if (!HudHandle.IsValid(hud))
{
    hud = HudBuilder.Create("AltimeterHUD")
        .ParentToReticle()
        .Anchor(0.15f, 0.84f)
        .Size(300, 25)
        .AddText("AltitudeText")
        .Build();
}

if (HudHandle.IsValid(hud))
    hud.Primary.SetRich("Altitude", 12.3f, UIColors.Shamrock, "m");


// Multi-line HUD
var meter = HudBuilder.Create("Carnometer")
    .ParentToReticle()
    .Anchor(0.15f, 0.95f)
    .Size(320, 100)
    .AddLines(4)
    .Build();

meter.Lines[0].SetRichWithRate("Total Damage", total, dps, UIColors.Rose);

// Overlay window
var window = UIWindow.Create("Settings", new Vector2(800, 600), "Mod Settings", scrollable: true);
UIWindow.CreateSectionHeader(window.Content, "General");
UIToggle.Create(window.Content, "Enable HUD", true, on => { /* ... */ });
UISlider.Create(window.Content, "Opacity", 0f, 1f, 0.8f, v => { /* ... */ });
UIButton.Create(window.Content, "Save", () => { /* ... */ }, UIButtonStyle.Primary);

// Dialog
UIDialog.Confirm("Scrap upgrades?", "This cannot be undone.", onConfirm: DoScrap);

// Tooltip
UITooltip.Attach(someButton.GameObject, "Does the thing");

Theme & scaling

Configurable HUD colors

// In your mod constructor:
valueColor = ConfigColor.Bind(config, "Colors", "ValueColor", UIColors.Sky,
    "Rich-text value color (hex RRGGBB or #RRGGBB).");

// When drawing:
hud.Primary.SetRich("Speed", speed, valueColor.Value, "m/s");

HUD positions use normalized anchors (0–1) so they stay consistent across resolutions. Window canvases use CanvasScaler with reference 1920×1080 and match width/height 0.5.

Vanilla Hide HUD

Gameplay HUDs created with HudBuilder automatically hide when the player enables the vanilla Hide HUD option (PlayerLook.DisablePlayerHUD). Call hud.SetActive(yourConfigEnabled) as usual — the library combines your desired state with the vanilla toggle.

// Optional: read the vanilla toggle yourself (e.g. custom non-HudHandle UI)
if (HudVisibility.IsHidden) { /* skip drawing */ }

Menu overlays (UIWindow, GearActionBar) are not affected.

Scene transitions (quit to menu / lobby)

Reticle-parented HUD is destroyed with the player when you quit to menu. The C# HudHandle wrapper is not a MonoBehaviour, so you must treat a dead handle as missing and rebuild:

// Every frame (or whenever you would create/update HUD):
if (!HudHandle.IsValid(hud))
{
    // optional: unregister reposition / other side state tied to the old rect
    hud = null;
    hud = HudBuilder.Create("MyHUD")
        .ParentToReticle()
        .Anchor(x, y)
        .Size(300, 25)
        .AddText()
        .Build();
    // re-register HudRepositionClient etc. after a successful Build()
}

if (!HudHandle.IsValid(hud))
    return; // player/reticle not ready yet

hud.Primary.SetRich("Speed", speed, UIColors.Sky, "m/s");

• hud.IsAlive / HudHandle.IsValid(hud) become false after scene unload
• Do not use if (hud != null) return alone in your create helper — a destroyed handle is still a non-null C# object
• GearActionBar rebuilds its host under the live Menu canvas automatically (library ticks it each frame)

HUD repositioning

SparrohUILib does not own HUD repositioning. Register with ModSettingsMenu yourself:

HudRepositionClient.Register(guid, "Altimeter", hud.Rect, anchorX, anchorY);

License

MIT — see LICENSE

Changelog

1.1.5

Fixes

• Dropdown layering — open option lists reparent to the root canvas and use override sorting (UITheme.DropdownSortingOrder) so they paint above later siblings and are not clipped by scroll masks
• Dropdowns flip above the trigger when there is not enough room below
• Added UIDropdown.IsOpen for consumers that track open state after reparent

1.1.4

Fixes

• Quit-to-menu / lobby reload — HUD handles parented to the player reticle no longer stay "alive" as stale C# wrappers after scene unload. HudHandle.IsAlive / HudHandle.IsValid let consumers detect teardown and rebuild
• HudHandleLife marks handles dead immediately when Unity destroys the root (player despawn / scene unload)
• HudVisibility prunes dead handles every tick and resets hide-state cache on scene unload
• GearActionBar host is invalidated on scene unload and ticked from the library plugin (no longer depends on a single consumer calling Tick)
• UITheme font cache cleared on scene unload so destroyed in-scene TMP fonts are not reused
• UIText accessors no-op safely when the underlying TMP was destroyed

API

• HudHandle.IsAlive — true while the Unity GameObject still exists
• HudHandle.IsValid(handle) — null-safe validity check
• HudVisibility.PruneDead / ResetSessionState
• UITheme.ClearFontCache

1.1.3

• HUD elements built via HudBuilder / HudHandle now respect the vanilla Hide HUD option (PlayerLook.DisablePlayerHUD)
• Added HudVisibility helper; HudHandle.SetActive stores desired visibility and applies it only when the vanilla HUD is shown
• Menu/overlay UI (windows, gear action bar) is unaffected

1.1.2

• Fixed gear action bar buttons requiring clicks slightly above the visible control
• GearActionBar now parents under the game Menu canvas (camera/blit UI space) instead of a separate overlay canvas
• Bar sizing uses menu reference pixels to avoid double-scaling with the menu CanvasScaler
• Bar re-attaches if the menu is destroyed/recreated; stays on top while gear details is open
• Nudged bar down/right so it sits cleanly in the curved menu chrome
• Gear action buttons are centered and grow outward as more mods register slots

1.1.1

• Fixed gear-bar / button hover being wiped when SetInteractable or SetStyle ran every frame
• UIButton now tracks hover/press state and reapplies the correct color after style/interactable changes
• GearActionBar.Register / SetText / SetInteractable only apply when values actually change
• Stronger, style-specific button hover/pressed colors for Default, Primary, Danger, and Active

1.1.0

• Added hex color parsing helpers: UIColors.TryParseHex, UIColors.ParseHex
• Added ConfigColor helper for binding hex color config entries with cached Color values

1.0.0

• Initial release of SparrohUILib
• Theme system with Mycopunk-inspired palette and resolution-aware scaling
• Core UI factory and layout helpers
• HUD builders (single-line and multi-line panels)
• Widgets: text, button, toggle, input field, panel, scroll view, separator, dropdown, slider, progress bar, tabs, tooltip
• Overlay windows and confirmation dialogs (per-window canvases)