11 KiB
Архитектура OpenWC
Цель
OpenWC состоит из двух продуктов на общей платформе:
- runtime-клиент WoW 3.3.5a для подключения к TrinityCore/AzerothCore;
- World and Gameplay Authoring Studio как набор dock-панелей, inspector-плагинов и viewport-инструментов внутри Godot Editor.
Оба продукта используют общие канонические модели, импорт данных и renderer preview, но не разделяют UI, lifecycle и права на изменение данных.
Архитектурные принципы
- Сервер авторитетен для боя, ресурсов, инвентаря, квестового прогресса и общего мира.
- Domain-модель не зависит от Godot Node, Control, Resource, сокетов или SQL.
- Renderer и UI являются проекциями состояния, а не владельцами gameplay-данных.
- Raw packet и server schema не выходят за границы adapter-слоя.
- Исходником пользовательского контента является версионируемый Content Project, а не рабочая БД.
- Любой тяжёлый импорт и bake отделяется от frame-critical runtime.
- Расширение выполняется через стабильные контракты, capability discovery и версионируемые схемы, а не через глобальные singleton-зависимости.
- Детерминированные преобразования отделяются от 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, команды и события: stable authored
ContentId, session-local EntityId, opaque wire WowGuid, namespaced
ServerEntryId, typed coordinates, SpellId, MoveIntent, EntityMoved.
Эти identity namespaces не конвертируются неявно и не содержат side effects;
их lifecycle и mapping определены в
modules/domain-identities.md.
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.