# UIA — UI, Lua, Addons and Audio

## Цель

Воспроизвести UI/addon semantics клиента 3.3.5a, сохранив возможность modern UI overlays и полноценную audio presentation.

## UIA-1. UI architecture

- Screen flow отделён от in-world HUD.
- UI читает immutable view models и отправляет intents.
- Godot Control tree является presentation backend, а не gameplay model.
- Input contexts: login, character, world, chat, modal, targeting, vehicle, cinematic.
- Scale, safe area, resolution, font и localization учитываются на уровне layout system.

## UIA-2. Frontend screens

- Data/license check, login, realm list и connection errors.
- Character selection/create/delete/rename.
- Race/class/customization previews тем же character renderer.
- Loading screens по map/instance, progress и cancellation policy.
- Disconnect/reconnect dialogs и account/server notices.

## UIA-3. FrameXML

- TOC parser: metadata, dependencies, optional deps, SavedVariables и load order.
- XML includes, templates, `virtual`, inheritance и named/anonymous objects.
- Frames, Regions, Textures, FontStrings, Layers и Scripts.
- Anchors, dimensions, strata, frame level, draw layers, clipping и scale.
- Widget types: Button, CheckButton, EditBox, Slider, StatusBar, ScrollFrame, MessageFrame, Tooltip, Cooldown, Model и Minimap.
- Handler scripts: OnLoad, OnEvent, OnUpdate, mouse/keyboard/drag/show/hide/value events.

## UIA-4. Lua runtime

- Внутренний `LuaRuntime` позволяет сравнить/заменить PUC-Rio 5.1.1 и `rilua`.
- Restricted libraries, byte strings, number semantics, globals, `bit` и error formatting.
- VM lifetime: one UI environment per client session/profile with controlled reset.
- Incremental GC имеет frame budget и metrics.
- Native functions возвращают stable Lua values, а не Godot/Rust/C++ objects напрямую.
- VM backend выбирается ADR после official + WoW-specific corpus.

## UIA-5. WoW API and event system

- API inventory строится из 3.3.5a FrameXML/Lua usage и независимых references.
- Реализация группируется: unit, spell, aura, item, quest, group, chat, map, CVar, bindings, frames.
- Event dispatcher имеет deterministic ordering, argument contracts и registration lifecycle.
- `OnUpdate` throttling не меняет original semantics в Blizzlike335.
- API, требующий server state, читает gameplay read model или создаёт intent; raw packets недоступны.
- Missing API выдаёт диагностируемую ошибку/coverage report, а не silent nil where incompatible.

## UIA-6. Security, taint and addons

- Secure/insecure execution origins.
- Protected functions/actions, secure templates и combat lockdown.
- Taint propagation through variables/tables/functions в пределах подтверждённой 3.3.5a модели.
- Addon memory/CPU/error isolation и configurable script limits без скрытого изменения default behavior.
- SavedVariables account/character scopes, serialization, corruption recovery и atomic writes.
- Addon compatibility tiers: loads, renders, functional, secure-combat verified.
- Headless addon runner и UI inspector входят в AuthoringStudio/Test Center.

## UIA-7. Default UI coverage

- Unit/player/target/focus/party/raid frames.
- Action bars, stance/pet/vehicle bars, cooldowns и keybindings.
- Buffs/debuffs, cast bars, combat text и errors.
- Bags, character, spellbook, talents, glyphs, skills, professions.
- Quest log/tracker/gossip, map/minimap/taxi.
- Chat, social, guild, calendar, LFG, PvP score.
- Vendor, trainer, bank, mail, auction, trade, loot и roll.
- Game menu, settings, macros, addons и help.

## UIA-8. Audio

- Typed DBC wrappers for SoundEntries, ZoneMusic, IntroMusic, Ambience and related tables.
- Decoder/streaming/cache for MP3/WAV with category budgets.
- Music day/night/zone transitions and crossfade.
- Ambient loops, random emitters, indoor/outdoor и weather.
- Positional world sounds, footsteps, water, spells, combat, NPC voice и UI feedback.
- Audio events come from presentation descriptors; UI/gameplay do not manipulate players directly.
- Device change, focus/mute policy, category volumes и missing sound diagnostics.

## UIA-9. Localization and accessibility

- Locale-aware fonts, fallback, text encoding и layout expansion.
- Keybindings fully remappable; mouse sensitivity/inversion and optional gamepad.
- UI scale, contrast/color-blind profiles, subtitle/text alternatives where possible.
- Critical state does not rely only on color/audio.
- Enhanced accessibility remains compatible with server and can coexist with Blizzlike visuals.

## References

- Original 3.3.5a FrameXML/Lua extracted from legally owned data is primary behavior corpus.
- `rilua`/PUC-Rio are VM candidates/oracles, not complete WoW UI.
- WowBench/Wowser/WowUnreal/WoWee provide API/event/loader test ideas.

## Gate

Default UI boots deterministically; selected real addons pass declared tiers; secure actions fail correctly during combat; Lua GC/OnUpdate remain within budgets; UI is replaceable without changing gameplay/network.