185 lines
11 KiB
Markdown
185 lines
11 KiB
Markdown
# Архитектура 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, команды и события: 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`](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`](../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.
|