RGX Foundation Decisions

This document answers a simple question:

Which capabilities does RGX own, which are already implemented, and how do we keep the runtime and authoring experience coherent as the framework grows?

Source review: 2026-10-06. The candidate TOC is 2.7.15-beta.4; the roadmap records 2.7.14 stable. Requirements below describe ownership, not an unimplemented shopping list. See Ace3 Analysis for the current capability map and Architecture for load order and modularity findings.

Core Rule

RGX should be elite-simple for addon authors:

• one dependency addon
• one clear API surface
• strong built-in defaults
• no unnecessary library chains
• no historical baggage unless it solves a real current problem

That means we only keep a foundation piece if it is required by real addon behavior, not because Ace3 happened to package it.

North Star

RGX-Framework is a shared runtime and addon-author toolkit. Its supported Lua API, declarative forms, canonical contract and optional authoring tools serve the same consumer experience. Developer tools are never runtime dependencies.

The goal is to let someone build a polished WoW addon quickly without first rebuilding the same low-level systems:

• lifecycle and load-order safety
• Blizzard event registration and cleanup
• timers, hooks, slash commands, and safe UI operations
• minimap buttons
• options panels and reusable controls
• shared fonts, textures, sounds, dropdowns, and theme colors
• callback modules for common WoW gameplay signals

Existing addons are the design references:

Addon	Framework Lesson
ETL	Traveler's Log events, lifecycle, minimap, and slash command ergonomics
SQP	large options panels, fonts, nameplate events, and reusable controls
RND	small utility addon pattern with direct events, timers, minimap, and settings
BLU v7	large sound/progression suite migration and shared media needs

When one of these addons repeats a pattern that another addon could reuse, that pattern belongs in RGX. When the behavior is product-specific, it stays in the addon.

What Is Actually Required

These are real framework requirements for the RGX direction.

1. Core addon object and module registry

RGX needs:

• one global framework object
• named module registration
• module lookup
• predictable initialization order
• a small lifecycle model
• BLU-style native runtime helpers for shared framework behaviors

Why this matters:

• every serious framework needs a stable place for shared systems to live

2. Shared media registries

RGX needs native registries for:

• fonts
• textures
• colors
• sounds

Why this matters:

• addon suites need one canonical source of shared media
• this is the part of LibSharedMedia that is genuinely useful

Design note:

• RGX can keep compatibility with BLU-style shared media behavior
• RGX does not need to literally become Ace/LSM internally to achieve that

3. Event and message dispatch

RGX needs:

• Blizzard event registration
• framework-wide messages
• module-local callback signaling when shared registries change

Why this matters:

• modules and consuming addons need a reliable way to react to game state and framework changes

Design note:

• this is why AceEvent and CallbackHandler exist
• RGX can solve the same problem natively

Related note:

• BLU already proved this direction with its own event/runtime layer, and RGX should absorb that style of native framework capability where it improves simplicity

4. SavedVariables and defaults

RGX needs a clean persistence layer for:

• global settings
• character settings
• profile-aware settings, switching and profile import/export (implemented)
• default application and reset behavior

Why this matters:

• any reusable framework eventually owns saved settings and defaults

Design note:

• RGX profiles do not imply AceDB-compatible namespaces or scope semantics
• simple defaults and clear storage rules matter more than feature count

5. Reusable option controls

RGX needs shared controls for:

• dropdowns
• color pickers
• font selectors
• texture selectors
• sound selectors
• toggles, sliders, edit boxes, tabs, grouped settings layouts

Why this matters:

• this is the difference between a media pack and a framework

6. Safe apply helpers

RGX needs one-line helpers that apply settings cleanly to:

• FontStrings
• status bars
• textures
• frames
• sounds

Why this matters:

• addon authors should not rebuild glue code every time they use RGX data

What Is Not Automatically Required

These are not mandatory just because Ace3 ships them.

LibStub

LibStub is not required for RGX itself.

Why Ace used it:

• Ace libraries were designed to be embedded independently into many addons
• that created runtime version conflicts
• LibStub solved library discovery and version negotiation

Why RGX does not need it:

• RGX is one dependency addon
• RGX owns its own module registry
• RGX does not need multiple copies of independently embedded internal libraries fighting over version precedence

Decision:

• do not make LibStub a core RGX dependency
• prefer BLU-style native module/runtime services inside RGX over separately embedded version stubs

CallbackHandler

CallbackHandler-1.0 is not required as an external dependency if RGX already provides strong native event/message/callback dispatch.

Why Ace used it:

• reusable observer pattern
• event registration API generation
• secure dispatch and callback bookkeeping

Why RGX does not need the external library:

• the pattern is useful
• the dependency is optional if RGX already implements the pattern internally

Decision:

• keep the capability
• do not require the external Ace implementation

AceSerializer

RGX already implements profile serialization/import-export in the database. A generic serializer or transport system is a separate capability, justified by:

• import/export
• addon-to-addon structured comms
• copy/paste data payloads
• future RGX-Mod data packaging

Decision:

• retain profile serialization and validate its persistence/round-trip behavior
• do not describe it as future work or infer general comm support from it

AceComm

Addon comm helpers are only required if RGX needs:

• addon-to-addon messaging
• chunked transmission
• synced data sharing

Decision:

• not a first-wave requirement
• becomes required when real cross-addon communication arrives

AceGUI / AceConfig scale

A fully generic mega-GUI layer is not automatically required on day one.

What is required instead:

• a small set of elite-simple, polished RGX controls
• shared layout primitives
• predictable settings wiring

Decision:

• build the small shared controls first
• grow only from real addon needs

Why Addon Authors Use Ace3

Ace3 became popular because it bundled a lot of common pain points in one place:

• addon object/lifecycle helpers
• event handling
• timers
• hooks
• database/profile handling
• slash commands
• options UI
• comm and serialization

That made it practical and familiar.

The key lesson is not "copy Ace3 exactly."

The real lesson is:

• frameworks win when they remove boring repeated work

RGX should keep that outcome while simplifying the implementation and API.

For the fuller breakdown of why Ace3 gets adopted and RGX's architectural distinction:

• see ACE3-ANALYSIS.md

RGX Direction

Keep three states explicit:

Implemented baseline

• registry/lifecycle, events/messages, timers, hooks, slash and combat queue
• profile-aware database, defaults, migrations and profile serialization
• fonts, colors, textures, sound and shared-media registries
• controls, options panels, imperative pages/columns/cards and design primitives
• minimap, broker, locale, auras/tooltip and capability-gated game modules
• RGXAddon, canonical schema and source-only authoring/conformance tooling

Implementation does not prove universal consumer adoption or client safety. Verify load/registration, flavor capabilities and observable behavior separately.

Current hardening and composition

• reliable DB ownership and persisted visual restoration in consumers
• one declaration vocabulary across runtime, schema, engine and MCP
• modular options rendering through existing UI/layout factories
• complete page/card composition beyond local declarative column flows
• theme/skin contracts that separate presentation from geometry and behavior

Need-driven future work

• bucket events and cross-client communication when maintained consumers need them
• reusable RGXMod trigger/condition/display primitives with current consumer value
• full native skins after source/asset evidence and client geometry acceptance

The Roadmap orders these outcomes; GitLab owns acceptance state.

Modularity Standard

Each module has one coherent owner and a small consumer interface. Internally it may compose private helpers without turning each helper into another public module. Library/game classification, declared dependencies and capability gates must agree with XML loading and initialization.

• Core owns shared lifecycle, dispatch, persistence and addon registration.
• UI owns controls, layout and rendering; Design/media own styling resources.
• Game modules own reusable WoW-domain state behind flavor adapters.
• Contract owns canonical authoring semantics; MCP/editor tooling adapts them.
• Consumers own feature policy, content and presentation choices.

Core owns declaration-time options validation and addon lifecycle. The current untagged follow-on delegates lazy control/layout rendering to a private seam in the existing UI options module. MCP validation delegates to the shared engine; the tagged beta.3 snapshot contains that correction, while rendering relocation remains separate local integration work. Neither requires another SDK/runtime or duplicate contract. See the ordered modularity work in Architecture.

Final Decision

If RGX's native event and message systems are good enough, then:

• RGX does not need LibStub
• RGX does not need external CallbackHandler-1.0
• RGX does not need Ace3 as a dependency

But RGX still needs the actual capabilities those libraries were solving:

• module organization
• dispatch
• persistence
• controls
• media registries
• profile serialization already in use; optional network comm when a real need exists

That is the standard to hold:

• keep the capability
• simplify the architecture
• remove the dependency unless it is truly buying us something