архитектура и цели для агентов

2026-07-10 10:28:37 +04:00
parent f561e52aa9
commit 93bfe114c0
46 changed files with 2826 additions and 55 deletions
@@ -0,0 +1,170 @@
+# Архитектура 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 запрещён.
+
+### 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 является отдельной явно подтверждаемой операцией.
+
+## Направление зависимостей
+
+```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/
+  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.