SimpleUnitFrames is a comprehensive, modular unit frame replacement for World of Warcraft Retail. Built on oUF with Ace3 configuration, it focuses on unit frame customization and optional PerformanceLib integration for advanced event coalescing, performance profiling, and diagnostics.
- Intelligent Frame Batching — DirtyFlagManager integration achieves 69.6% event coalescing efficiency with zero dropped frames
- Smart Priority System — Automatic frame update prioritization (CRITICAL/HIGH/MEDIUM/LOW) based on unit importance
- Performance Breakthrough — 16.66ms average frame time (60 FPS), P99=28ms, with 1,963 events batched per session
- Event Expansion — Added 14 new events to batching pipeline (13 UNIT_SPELLCAST_* events + UNIT_AURA)
- Top Event Reductions — UNIT_HEALTH 78%, UNIT_POWER 72%, UNIT_AURA 54%, UNIT_ABSORB 76%, THREAT 73%
- Blizzard Frame Integration — Per-frame hide controls for default unit frames with Edit Mode visibility toggle and global options
- Health Color Hardening — Threat/reaction/class colors now safe against WoW 12.0.0+ secret value restrictions
- Data Text/Bars System — New draggable data bar framework with Shift+click-restricted drag handles, XP/Reputation fade controls, and dynamic repositioning
- Portrait Alpha Syncing — Portraits now follow frame fader alpha for consistent frame transparency effects
- Safe Theming Helpers — Added
ApplySUFBackdropColors()utility for backdrop styling with safe color fallbacks - Plugin Compatibility — Broad oUF compatibility shims for aura iteration, unpacking, and secret-value handling across different runtime environments
- Options V2 Theme Propagation — Active Options V2 preset now skins debug/performance windows for visual consistency
- Perf Command Aliases — Added
/sufperfas primary performance dashboard command with/libperfalias support
- Frame Types — Player, Target, Target-of-Target, Focus, Pet, Party, Raid, and Boss frames
- Customization — Per-unit sizing, media, fonts, portraits, castbars, and aura sizing
- Advanced Rendering — Tag-driven text system with health, power, absorbs, heal prediction, and custom SUF tags
- Aura System — Configurable aura display with icon sizing, buff/debuff filtering, and preview tooltips
- Edit Mode Integration — Full compatibility with Blizzard Edit Mode for frame positioning
- DirtyFlagManager Integration (v1.26.0) — Intelligent frame update batching system:
- 69.6% Event Coalescing efficiency (1,963 events batched per gameplay session)
- Smart Priority System — Auto-assigns CRITICAL/HIGH/MEDIUM/LOW based on unit type
- Frame Time Optimization — 16.66ms avg (60 FPS), P99=28ms, 0 dropped frames
- Top Event Reductions — UNIT_HEALTH 78%, UNIT_POWER 72%, UNIT_AURA 54%
- 4 Helper Functions — MarkFrameDirty, MarkAllFramesDirty, MarkFramesByUnitTypeDirty, GetFrameUpdatePriority
- PerformanceLib Integration — Optional advanced performance systems including:
- Event coalescing with adaptive priorities and emergency flush handling
- Frame time budgeting and frame pooling for GC reduction
- Real-time performance dashboard (
/sufperf) - Timeline profiling with bottleneck analysis (
/SUFprofile) - ML-based priority optimization (learns from gameplay patterns)
- Relevance Filtering — Smart event queueing reduces unnecessary event pressure during combat
- Diagnostics Panel — Real-time logs with system filters, debug channels, and exportable data
- Draggable Data Bars — Repositionable bars for XP, reputation, and custom data displays
- Shift+Click Drag Handles — Drag handles restricted to Shift+click for accidental protection
- XP/Reputation Control — Per-bar visibility and fade behavior tied to data bar settings
- Customizable Text — Data text system with multiple text display options
- Unified Options Window — Tabbed interface with search v2 (relevance scoring, grouped results, keyboard navigation)
- PerformanceLib Tab — Preset selection, snapshot metrics, and integration shortcuts
- Global Settings — Universal options including Blizzard frame visibility control
- Per-Unit Presets — Tag preset system (compact/healer/tank/dps/minimal) for quick style switching
- Import/Export — Profile wizard with validation, preview, and rollback on failure
- Minimap/LDB Support — Launcher with quick-access actions and settings menu
- Download latest release from GitHub Releases
- Extract the
.zipfile to yourWorld of Warcraft\_retail_\Interface\AddOns\folder - Verify two folders created:
SimpleUnitFrames\(main addon)PerformanceLib\(bundled performance addon)
- Reload UI or restart WoW
- Place
SimpleUnitFramesin your WoW AddOns folder - (Optional) Install
PerformanceLibfor advanced performance features - Reload UI or restart WoW
| Command | Purpose |
|---|---|
/suf |
Open SimpleUnitFrames options |
/sufdebug |
Toggle debug console with logs and filtering |
/sufperf |
Toggle real-time performance dashboard (requires PerformanceLib) |
/libperf |
Alias to /sufperf |
/SUFprotected |
Show protected operations queue stats |
/suf perflib |
Toggle performance dashboard via /suf command router |
Use the helper script to maintain version format 1.<majorX>.<smallX>.<mdyy>:
# Small change: increment smallX, keep majorX
powershell -ExecutionPolicy Bypass -File .\scripts\bump-version.ps1 -ChangeType small
# Major change: increment majorX, reset smallX to 0
powershell -ExecutionPolicy Bypass -File .\scripts\bump-version.ps1 -ChangeType majorAutomated scripts for creating production-ready releases:
# Build release archive (auto-detects version from TOC, bundles PerformanceLib)
.\build-release.ps1
# Publish to GitHub (auto-detects version, prompts for confirmation)
$env:GITHUB_TOKEN = 'your-github-token'
.\publish-release.ps1
# Or use dry-run to preview
.\publish-release.ps1 -DryRunFeatures:
- Auto-detection of PerformanceLib from adjacent directory
- Comprehensive exclusion of dev files (.agents, .claude, .github, scripts, docs, etc.)
- Production-clean archives with only runtime files
- Automatic GitHub release creation with release notes
This repository now bumps SimpleUnitFrames.toc automatically on every commit via .githooks/pre-commit:
- Default behavior is
auto:majorif staged changes (excluding TOC) are large (>=20 filesor>=1000 lines).smallotherwise.
- Override per-commit:
SUF_VERSION_BUMP=major git commit ...SUF_VERSION_BUMP=small git commit ...SUF_SKIP_VERSION_BUMP=1 git commit ...to bypass.
Threshold overrides:
SUF_MAJOR_FILE_THRESHOLD(default20)SUF_MAJOR_LINE_THRESHOLD(default1000)
/SUFprofile start # Begin timeline recording (max 10000 events)
/SUFprofile stop # End recording
/SUFprofile analyze # Show FPS metrics, frame time percentiles, coalescing stats, bottlenecks
/SUFprofile export # Copy timeline data to clipboard
/SUFpreset low|medium|high|ultra # Change performance preset
/SUFpreset auto on|off # Toggle auto-optimization based on hardware
/SUFpreset recommend # Get preset recommendations
Expected Baseline (v1.26.0+):
- Coalescing Efficiency: 69.6% (1,963 of 2,816 events batched)
- Frame Time: Avg 16.66ms (60 FPS), P99 28ms
- Dropped Frames: 0 (perfect stability)
- Event Reductions: UNIT_HEALTH 78%, UNIT_POWER 72%, UNIT_AURA 54%, UNIT_ABSORB 76%, THREAT 73%
SimpleUnitFrames provides extended tag support beyond standard oUF tags:
| Tag | Purpose |
|---|---|
[suf:absorbs] |
Absorb shield amount with condensed formatting |
[suf:incoming] |
Incoming heal prediction |
[suf:ehp] |
Effective health (health + absorbs) |
[suf:missinghp] |
Missing health value |
[suf:missingpp] |
Missing power value |
[suf:status] |
Unit status (dead, ghost, offline) |
[suf:name] |
Unit name with class color |
Note: Due to WoW 12.0.0+ secret value restrictions, some numeric prediction values may be unavailable in certain contexts. SUF prioritizes stable, taint-safe rendering over unreliable numeric display.
- Secret Values (WoW 12.0.0+) — Some prediction API returns are restricted; SUF uses safe fallback colors and text when values are unavailable
- PerformanceLib Features — Advanced diagnostics and ML optimization only available when PerformanceLib addon is installed
- Broker/LDB — Minimap behavior depends on optional broker libraries present in the addon environment
If you are extending SUF internally/modules:
-- Unit Configuration
addon:GetUnitSettings(unitType)
addon:GetUnitFontSizes(unitType)
addon:GetUnitStatusbarTexture(unitType)
addon:GetUnitCastbarSettings(unitType)
addon:GetUnitLayoutSettings(unitType)
addon:GetUnitHealPredictionSettings(unitType)
addon:GetUnitCastbarColors(unitType)
addon:GetUnitAuraSize(unitType)
-- Performance Integration
addon:SetPerformanceIntegrationEnabled(enabled[, silent])
addon:QueuePerformanceEvent(eventName, ...)
-- DirtyFlagManager Integration (v1.26.0+)
addon:GetFrameUpdatePriority(frame) -- Get priority for frame (CRITICAL/HIGH/MEDIUM/LOW)
addon:MarkFrameDirty(frame, priority) -- Queue single frame for batched update
addon:MarkAllFramesDirty(priority) -- Queue all frames for batched update
addon:MarkFramesByUnitTypeDirty(unitType, priority) -- Queue frames by unit type
-- Profile Management
addon:SerializeProfile()
addon:DeserializeProfile(input)
addon:ValidateImportedProfileData(data)
addon:BuildImportedProfilePreview(data[, report])
addon:ApplyImportedProfile(data)- SimpleUnitFrames.lua — Core addon initialization, profile management, unit configuration, and custom tag registration
- Core/ProtectedOperations.lua — Unified combat lockdown handling with priority-based operation queueing
- Modules/UI/ — Options window, debug panel, and data bar system with theming helpers
- Units/ — oUF unit frame builders for each frame type
- DEVELOPER_NOTES.md — Safe extension patterns and contribution guidelines
- MIGRATION.md — Profile migration and import system details
- PROTECTED_OPERATION_ANALYSIS.md — Combat lockdown handling deep dive
- Use
addon:QueueOrRun(func, opts)for all frame mutations during combat - Localize frequently-called globals with "PERF LOCALS" pattern for performance
- Use
SafeNumber(),SafeText(), andSafeAPICall()wrappers for WoW 12.0.0+ compatibility - Reference copilot-instructions.md for project conventions and integration patterns
- oUF — Unit frame and element system
- Ace3 — AceAddon-3.0, AceDB-3.0, AceGUI-3.0, AceConsole-3.0, AceEvent-3.0, AceSerializer-3.0
- LibSharedMedia-3.0 — Texture and font registration/lookup
- LibSerialize — Data serialization
- LibDeflate — Data compression
- LibDualSpec-1.0 — Per-specialization profiles
- PerformanceLib (optional) — Event coalescing, profiling, ML optimization, diagnostics
- LibDataBroker-1.1 (optional) — Minimap/LDB broker support
- LibDBIcon-1.0 (optional) — Minimap icon management
- LibDispel-1.0 — Dispel helper functions
- LibCustomGlow-1.0 — Glow effects
- LibSimpleSticky — Window snapping
- LibTranslit-1.0 — Text transliteration
- LibAnim — Animation utilities
- TaintLess — Taint management
- LibAceConfigHelper — Configuration UI helpers
- UTF8 — Unicode text handling
- WoW Version — Retail (interface version 120001, WoW 12.0.0+)
- Saved Variables —
SimpleUnitFramesDB - Lua Version — Lua 5.1 (WoW standard)
- PerformanceLib — Optional (gracefully degrades if not installed)
- Grevin — SimpleUnitFrames author and maintainer
- oUF Authors — Foundational unit frame framework and tag system
- Ace3 Community — AceAddon, AceDB, AceGUI, AceConsole, and related libraries
- Gethe & wow-ui-source Contributors — Blizzard UI reference implementations
- Warcraft Wiki Contributors — API and widget documentation used during development
- UnhaltedUnitFrames (UUF) — Early frame design and architecture reference points
- WoW Addon Ecosystem — Patterns and compatibility learnings from retail addon authors
- PerformanceLib — Optional performance systems (event coalescing, profiling, ML optimization)
- LibSharedMedia-3.0 — Texture and font management
- LibDualSpec-1.0 — Per-spec profile support
- LibDataBroker-1.1 & LibDBIcon-1.0 — Minimap/LDB support
- LibDispel-1.0, LibCustomGlow-1.0, LibSimpleSticky — UI enhancements
- LibDeflate, LibSerialize, LibAceConfigHelper — Data handling and configuration
- LibTranslit-1.0, UTF8, TaintLess — Text processing and taint-safety helpers
SimpleUnitFrames follows the project repository license.
PerformanceLib integration remains under its own library license terms.