Advanced Interface Optimization System

What is AIOS?

AIOS (Advanced Interface Optimization System) is a modular World of Warcraft addon kernel designed to replace legacy library stacks with a unified service‑oriented architecture.

Kernel architecture specification

Boot sequence (deterministic order):

copyMeta reflection (BuildInfo + Environment)
 → ServiceRegistry initialization
 → Core services defined (Logger, EventBus, Lean, …)
 → Subsystems attach
 → Validation pass
 → AIOS_Core_Ready emitted

No service is accessible before its dependencies are satisfied. All access via ServiceRegistry:Get().

Service lifecycle

copystate = "none" | "pending" | "ready"

• none – defined but not yet instantiated.
• pending – factory invoked, waiting for async dependencies (if any).
• ready – fully constructed, available for use.

Boot sequence

copyMeta reflection (BuildInfo + Environment)
  → ServiceRegistry initialization
  → Core services defined (Logger, EventBus, Lean, …)
  → Subsystems attach
  → Validation pass
  → AIOS_Core_Ready emitted

ServiceRegistry internal model

copyService entry = {
  name, version, factory, instance,
  state = "none" | "pending" | "ready",
  namespace, aliases
}

EventBus execution model

Synchronous emit · safe emit (pcall) · delayed · throttled · coroutine‑based async · reactive streams.

copyStream(event) → Filter → Map → Throttle/Debounce → Subscribe

Lean memory engine

Pools: ObjectPool, TablePool, StringPool, Numeric, GUI. Borrow/Return must always pair.

Timer engine internals

copySchedule → Active → Tick → Complete/Repeat → Release

Codec architecture

Registry‑based: RegisterEncoder/Decoder/Compression/Hasher. Compression engines are pluggable backends.

Protect layer

Isolates unsafe WoW API usage: safe context detection, deferred execution, combat lockdown safety.

Saved system

Namespaced storage · versioned schema · migration pipeline · optional reactive store.

Internal API classification

Fully indexed API reference

Grouped by subsystem – method names only, quick lookup.

ServiceRegistry — complete API

copyDefine(name, version, factory)
Alias(from, to)
List(pattern) → table
Get(name) → service
Has(name) → bool
TryGet(name) → service, ok
GetVersion(name) → string
GetAll() → table
Dump(), DumpAll(), DumpNamespace(ns), DumpAliases()
Summary() → string
Search(term) → table
NamespaceImpl(name), ListNamespaces(), NamespaceCount()
ClearNamespaces()  — use with care
ValidateImpl(name, service), ValidateAll()
Diagnostics()

EventBus · Async · Reactive streams

copyInit(), IsReady()
Listen(event, handler), Once(event, handler), Unlisten(event, handler)
ListenWoW(event, handler), UnlistenWoW(event)
Emit(event, ...), EmitSafe(event, ...), EmitDelayed(event, delay, ...)
EmitThrottled(event, interval, ...), EmitBridge(event, ...)
Clear(), Count(event)
RunAsync(fn, ...) → thread, Await(seconds), Sequence(tasks), Delay(fn, delay, ...)
CancelAllAsync(), DumpAsync()
Stream(event) → stream, Filter(fn), Map(fn), Throttle(sec), Debounce(sec), Take(limit)
Subscribe(fn), Emit(...), Destroy()

Lean — memory pooling system

copyInit(), IsReady()
AcquirePool(kind), Acquire(kind), Release(kind, obj)
RegisterExtension(name, extension)
ObjectPool: Borrow(), Return(obj), GetStats()
TablePool: Borrow(), Return(tbl), GetStats()
StringPool: Intern(s) → string, Count()

Logger — structured + ringbuffer + sinks

copyInitialize()
Info(tag, fmt, ...), Warn(tag, fmt, ...), Error(tag, fmt, ...), Debug(tag, fmt, ...)
Print(level, tag, msg), ResolveAuthority(tag)
RingBuffer: New(maxEntries), Add(msg), GetRecent(n), Clear(), Size()

Timers — scheduling, groups, profiler

copySchedule(name, delay, callback)
After(delay, callback), Every(interval, callback)
Throttle(key, delay, callback), Debounce(key, delay, callback)
Cancel(name), CancelAll(), CancelPattern(pattern), CancelGroup(group), CancelHandle(handle)
RegisterToGroup(groupName, timerObj)
PauseGroup(groupName), ResumeGroup(groupName), RemoveGroup(groupName), ListGroups()
Tick(elapsed), RecordGroup(groupName, latency)
Enqueue(id, delay, callback, repeating, priority), ClearQueue()

Saved — namespaced storage, migrations, reactive

copyInit()
Get(namespace, key), Set(namespace, key, value), Reset(namespace)
GetAsync(namespace, key, callback), SetAsync(namespace, key, value, callback)
GetProfile(), SwitchProfile(profile), CopyProfile(source, target)
RegisterSchema(namespace, schema, version)
CreateReactiveStore(namespace, scope)

Locale — i18n, learning, frame scan

copyRegister(lang, tbl)
RegisterAddon(addon, translations)
RegisterLanguage(lang, data)
RegisterAddonLocale(addon, lang, data)
Translate(key, fallback), Format(key, ...)
OnMissingKey(key)
ScanFrames(), FlushLearned(), ToggleLearning(state)
DumpLearned(), DumpLocaleStats()
GetSystemLocale(), GetRegionName()

Protect — secure execution & API wrapper

copyIsSafeContext()
SetContext(context, blocked)
Execute(func, ...), Defer(func, ...), FlushQueue()
Wrap(func)
UnitName(unit), UnitHealth(unit), UnitAura(unit, index, filter)
CreateFrame(frameType, name, parent, template)
SendChatMessage(msg, chatType, language, channel)
Initialize(), GetDiagnostics(), Reset(), GetLegacyCompatibility()

Codec — encoders, compression, hashing

copyRegisterEncoder(name, handler), RegisterDecoder(name, handler)
RegisterCompression(name, handler), RegisterHasher(name, handler)
RegisterUtility(name, handler)
Encode(name, data), Decode(name, data)
Compress(name, data), Decompress(name, blob)
Hash(name, data), GetStats(), Dump()

Meta — BuildInfo, Environment, debug

copyBuildInfo: Reflect(force), Get(field), Summary()
Environment: Reflect(force), Get(key), Summary(), Init()
GetMemoryUsage(), GetUptime(), GetServiceCount(), PrintDebugSummary()

Frames module — quick UI helpers

copyCreateFrame(frameType, parent, name)
Fill(frame, parent)
CreateOverlay()
CreatePanel(parent, width, height)
CreateButton(parent, name)
SetOnClick(handler)

AIOS Stability Contract

Effective for v1.x releases

What is guaranteed stable

• All public methods listed in the API reference (excluding those marked Advanced or Internal).
• Method names, signatures, and expected behavior will not change in a backward‑incompatible way within the same MAJOR version.
• Deprecated APIs will remain functional for at least one full minor release cycle before removal.
• The kernel boot sequence and the emission of AIOS_Core_Ready.

What is NOT guaranteed stable

• Internal subsystem implementations (e.g., compression backends, hash internals, timer priority algorithm).
• Diagnostic helper outputs (Dump(), GetStats() formatting).
• Any API explicitly marked as Internal or Experimental.

Versioning & Semantic Policy

AIOS strictly follows Semantic Versioning 2.0.0.

• MAJOR – breaking public API changes
• MINOR – backward‑compatible additions
• PATCH – bug fixes, internal refactors

Diagnostics & system checks

Each module provides Diagnostics(), Dump() or GetStats(). The kernel also exports /aiosdiag command.

MyAddon — complete working example

A fully functional AIOS-powered addon demonstrating core framework features.

MyAddon.toc

copy## Interface: 110200
## Title: MyAddon
## Author: You
## Version: 1.0.0
## Dependencies: AIOS
## SavedVariables: MyAddonDB

MyAddon.lua

MyAddon.lua

copy--[[-----------------------------------------------------------------------------
MyAddon Demo - Complete AIOS example
-----------------------------------------------------------------------------]]--

local AIOS = _G.AIOS
if not AIOS then return end

local function Init()
    local SR = AIOS.ServiceRegistry
    local Logger = SR:Get("Logger")
    if not Logger then return end

    Logger:Info("MyAddon Demo initializing")

    -- Locale Setup
    local Locale = SR:Get("Locale")
    Locale:RegisterAddon("MyAddon")
    Locale:RegisterAddonLocale("MyAddon", "enUS", {
        TITLE = "AIOS Demo",
        CLOSE = "Close"
    })
    Locale:RegisterAddonLocale("MyAddon", "esES", {
        TITLE = "Demostración AIOS",
        CLOSE = "Cerrar"
    })
    Locale:RegisterAddonLocale("MyAddon", "frFR", {
        TITLE = "Démo AIOS",
        CLOSE = "Fermer"
    })
    local titleText = Locale:Translate("MyAddon", "TITLE")
    local closeText = Locale:Translate("MyAddon", "CLOSE")

    -- TablePool Test
    local TablePool = SR:Get("TablePool")
    if TablePool then
        local tbl = TablePool:Borrow()
        tbl.test = true
        TablePool:Return(tbl)
        Logger:Info("TablePool verified")
    end

    -- Create Frame
    local frame = CreateFrame("Frame", "MyAddon_DemoFrame", UIParent, "BackdropTemplate")
    frame:SetSize(320, 180)
    frame:SetPoint("CENTER")
    frame:SetMovable(true)
    frame:EnableMouse(true)
    frame:RegisterForDrag("LeftButton")
    frame:SetScript("OnDragStart", frame.StartMoving)
    frame:SetScript("OnDragStop", frame.StopMovingOrSizing)
    frame:SetBackdrop({
        bgFile = "Interface/Tooltips/UI-Tooltip-Background",
        edgeFile = "Interface/Tooltips/UI-Tooltip-Border",
        edgeSize = 12,
        insets = { left = 4, right = 4, top = 4, bottom = 4 },
    })
    frame:SetBackdropColor(0, 0, 0, 0.9)

    local title = frame:CreateFontString(nil, "OVERLAY", "GameFontNormalLarge")
    title:SetPoint("TOP", 0, -10)
    title:SetText(titleText)

    local counterText = frame:CreateFontString(nil, "OVERLAY", "GameFontHighlightLarge")
    counterText:SetPoint("CENTER")
    counterText:SetText("0")

    -- Timer
    local Timers = SR:Get("Timers")
    local counter = 0
    Timers:Every(1, function()
        counter = counter + 1
        counterText:SetText("Timer: " .. counter)
    end)

    -- Exit Button
    local closeBtn = CreateFrame("Button", nil, frame, "UIPanelButtonTemplate")
    closeBtn:SetSize(80, 24)
    closeBtn:SetPoint("BOTTOM", 0, 10)
    closeBtn:SetText(closeText)
    closeBtn:SetScript("OnClick", function()
        frame:Hide()
        Logger:Info("Demo frame closed")
    end)

    -- EventBus Test
    local EventBus = SR:Get("EventBus")
    EventBus:Listen("MY_DEMO_EVENT", function(msg)
        Logger:Info("EventBus received: %s", msg)
    end)
    EventBus:Emit("MY_DEMO_EVENT", "EventBus Working")

    Logger:Info("MyAddon Demo ready")
end

-- Safe Boot Pattern
local hub = AIOS.SignalHub
if hub and hub.Listen then
    hub:Listen("AIOS_Core_Ready", Init)
else
    local f = CreateFrame("Frame")
    f:RegisterEvent("PLAYER_LOGIN")
    f:SetScript("OnEvent", Init)
end

What this demo shows

• Safe boot pattern — waits for AIOS_Core_Ready with fallback
• Logger — info messages throughout initialization
• Locale — addon-scoped translations for English, Spanish, French
• TablePool — borrow/return pattern for memory efficiency
• Timers — 1-second repeating timer updating a UI counter
• EventBus — custom event emission and listening
• Frame management — movable frame with backdrop and exit button

Building your first AIOS addon

See the MyAddon sample above for a complete working example. Key steps:

• Add ## Dependencies: AIOS to your .toc
• Wait for AIOS_Core_Ready via SignalHub
• Access services via ServiceRegistry:Get()
• Use Logger for debugging, Locale for translations, Timers for scheduling
• Always return pooled objects to Lean

Code examples

copyAIOS.SignalHub:Listen("AIOS_Core_Ready", function()
  local SR = AIOS.ServiceRegistry
  local Logger = SR:Get("Core::Logger")
  local Lean = SR:Get("Core::Lean")
  
  Logger:Info("Example", "Addon loaded")
  
  SR:Define("Module::Greet", "1.0.0", function()
    return { say = function() print("hello") end }
  end)
  
  local t = Lean:Acquire("table")
  -- use table
  Lean:Release("table", t)
end)