# Архитектура OpenWC

## Цель

OpenWC состоит из двух продуктов на общей платформе:

- runtime-клиент WoW 3.3.5a для подключения к TrinityCore/AzerothCore;
- World and Gameplay Authoring Studio как набор dock-панелей, inspector-плагинов и viewport-инструментов внутри Godot Editor.

Оба продукта используют общие канонические модели, импорт данных и renderer preview, но не разделяют UI, lifecycle и права на изменение данных.

## Архитектурные принципы

1. Сервер авторитетен для боя, ресурсов, инвентаря, квестового прогресса и общего мира.
2. Domain-модель не зависит от Godot Node, Control, Resource, сокетов или SQL.
3. Renderer и UI являются проекциями состояния, а не владельцами gameplay-данных.
4. Raw packet и server schema не выходят за границы adapter-слоя.
5. Исходником пользовательского контента является версионируемый Content Project, а не рабочая БД.
6. Любой тяжёлый импорт и bake отделяется от frame-critical runtime.
7. Расширение выполняется через стабильные контракты, capability discovery и версионируемые схемы, а не через глобальные singleton-зависимости.
8. Детерминированные преобразования отделяются от side effects и тестируются без сцены.

## Контекст системы

```text
Original 3.3.5a data ──► Import/Cache ───────────────┐
                                                     ▼
TrinityCore/AzerothCore ◄── Network Adapter ◄── Runtime Client
          ▲                                          ▲
          │ SQL/change sets                          │ read models
          │                                          │
     Build/Deploy ◄── Content Project ◄── Godot Editor Tools
```

## Слои runtime

### Domain

Содержит идентификаторы, value objects, команды и события: `EntityId`, `WowGuid`, `MapPosition`, `SpellId`, `MoveIntent`, `EntityMoved`. Не содержит side effects.

### Gameplay

Владеет `WorldState`, entity registry, локальным игроком, movement prediction, targeting, combat presentation state, spells, auras, inventory, quests и social state. Принимает domain events и формирует intents/commands.

### Network

Владеет transport, SRP/auth session, realm/world session, crypt, framing, opcode registry, packet codecs, update fields и replay traces. Публикует только domain events. Профиль протокола фиксируется как `wotlk_335a_build_12340`; различия ядер находятся в adapters/capabilities.

### Render

Владеет ADT/WDT/WDL, M2, WMO, liquids, sky, lighting, weather visuals, animation presentation, LOD, culling, caches и frame budgets. Текущее состояние и ограничения описывает [`../RENDER.md`](../RENDER.md).

Renderer получает `StreamingFocus`, `WorldVisualSnapshot` и presentation-команды. Он НЕ ДОЛЖЕН читать packets, SQL или gameplay input.

### UI

Владеет login/realm/character screens, HUD и FrameXML/Lua-compatible presentation. UI читает immutable view models и отправляет intents. Lua API получает capability-based facade; прямой доступ к network, filesystem и editor API запрещён.

Lua VM подключается через внутренний `LuaRuntime` interface. `rilua` и PUC-Rio Lua 5.1.1 рассматриваются как заменяемые backend-кандидаты; TOC, FrameXML, WoW API, event dispatch, SavedVariables, secure actions и taint не зависят от конкретного VM API. Rust/C++ типы не выходят за runtime adapter boundary.

### Audio

Владеет music, ambience, positional SFX, UI sounds и voice playback. Получает zone/combat/weather events и DBC-backed descriptors. Gameplay не управляет AudioStreamPlayer напрямую.

### Application

Собирает зависимости, управляет lifecycle `Boot → Login → Realm → CharacterSelect → Loading → InWorld → Disconnect` и режимами `RenderSandbox`, `OfflineSandbox`, `ProtocolSandbox`, `GameClient`.

## Слои authoring

### Editor shell

Godot `EditorPlugin` регистрирует workspace, docks, inspectors, gizmos, importers и команды. Shell не содержит правил конкретных таблиц или квестов.

### Authoring domain

Канонические редактируемые сущности: map, zone, terrain patch, placement, creature, gameobject, quest, dialogue, loot, encounter, dungeon package и localization bundle.

### Commands and history

Каждая мутация оформляется командой с `execute`, `undo`, validation impact и change description. Инструменты не меняют scene tree или файлы в обход общей истории операций.

### Server data adapters

Адаптеры TrinityCore/AzerothCore преобразуют канонические сущности в snapshot и change set. Неизвестная версия схемы разрешает read-only inspection, но блокирует запись.

### Build and deployment

Pipeline выполняет validate, allocate IDs, bake, diff, package, generate SQL, dry-run, apply-to-dev и verification. Production deployment является отдельной явно подтверждаемой операцией.

### Navigation tooling

Navigation build является частью authoring/build pipeline, а не renderer или authoritative client gameplay. Optional backend `recast-rs` получает каноническую triangle/collision geometry и создаёт OpenWC navigation cache для editor preview, reachability validation и path diagnostics. Первая интеграция должна быть process/CLI boundary; Rust GDExtension допускается только после стабильного формата обмена и измеренной необходимости интерактивных запросов.

Server `mmaps` остаются отдельным артефактом. Экспорт в TrinityCore/AzerothCore формат запрещено считать поддержанным, пока compatibility tests не докажут совпадение coordinates, Recast parameters, tile layout и server query behavior.

## Направление зависимостей

```text
app ─────► gameplay, network, render, ui, audio
editor ──► authoring, content, render-preview, server-adapters
network ─► domain
gameplay ► domain
render ──► domain presentation contracts
ui ──────► view models and intents
content ─► domain schemas
domain ──► standard language/runtime only
```

Запрещены зависимости `render → network`, `ui → packet codec`, `gameplay → material`, `domain → Node`, `server adapter → editor Control`.

## Runtime data flow

```text
Input/UI → Intent → Gameplay → Network command → Server
Server → Packet codec → Domain event → Gameplay state
Gameplay state → Presenters → Render/UI/Audio
```

Для локального движения допускается prediction. Reconciliation всегда использует server snapshot; correction policy должна быть измеримой и тестируемой.

## Предлагаемая структура кода

```text
src/
  app/
  domain/
  gameplay/
  network/
    protocol/wotlk_335a/
    adapters/trinitycore/
    adapters/azerothcore/
  render/
  ui/
  audio/
  content/
  editor/
  server_data/
  build_pipeline/
    navigation/
  shared/
  tests/
addons/
  openwc_editor/
```

Существующий `addons/mpq_extractor` остаётся content infrastructure. Его runtime API следует закрыть интерфейсами asset repository и import service.

## Контракты расширения

- `ProtocolProfile` — opcodes, update fields, codecs, capabilities.
- `ServerSchemaAdapter` — inspect, import, diff, generate, validate.
- `ContentTypeDescriptor` — schema, inspector, validator, compiler.
- `WorldRenderer` — streaming focus и entity presentation.
- `GameplaySystem` — commands/events без scene dependency.
- `EditorTool` — selection, command creation и gizmo, без прямой записи.
- `TestFixtureProvider` — обезличенные packets, DB snapshots и content fixtures.

Каждый контракт версионируется. Несовместимое изменение требует migration и ADR.

## Потоки и производительность

- Network thread читает байты; main/game thread применяет domain events.
- Worker pool выполняет parsing, decompression, import и bake.
- Godot scene tree и GPU resource finalization изменяются только на допустимом потоке и ограничиваются budget scheduler.
- Очереди имеют bounded capacity, cancellation и telemetry.
- Editor-задачи показывают progress, позволяют cancel и не блокируют UI.

## Безопасность и законность

- Репозиторий не распространяет proprietary game data, ключи, пароли или production dumps.
- Credentials хранятся вне Content Project и логов.
- Packet traces и DB fixtures редактируются/обезличиваются.
- Lua/addons исполняются с документированными возможностями и лимитами.
- Direct DB apply доступен только для явно выбранной dev-среды с backup/checkpoint.

## ADR

Значимые решения записываются в `docs/adr/NNNN-title.md`: контекст, варианты, решение, последствия и migration. ADR требуется для изменения границы слоя, формата контента, координат, authoritative policy или поддерживаемого server profile.