open-wc/docs/ARCHITECTURE.md

Архитектура 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 и тестируются без сцены.

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

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.

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.

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

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

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 должна быть измеримой и тестируемой.

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

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.