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

docs/ARCHITECTURE.md

@@ -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.

docs/CLIENT_FEATURES.md

@@ -0,0 +1,117 @@
+# Карта функций клиента WoW 3.3.5a
+
+## Назначение
+
+Это coverage map, а не обещание реализовать всё одновременно. Для каждой строки в будущем ведутся статусы `Not started`, `Research`, `Prototype`, `Playable`, `Compatible`, `Verified` и ссылки на issue/spec/tests.
+
+## Platform и данные
+
+- MPQ archive chain, locale и patch precedence.
+- BLP, DBC, DB2 при расширении профиля, WDT/WDL/ADT, M2/SKIN, WMO, animation, particles, ribbons, cameras.
+- Cache/versioning, import diagnostics, missing/corrupt asset policy.
+- Typed DBC access: maps, areas, races, classes, characters, items, creatures, spells, talents, factions, sounds, liquids, lights, maps and taxi.
+- Settings, keybindings, locale, screenshots, logs, crash recovery и accessibility options.
+
+## World presentation
+
+- Terrain layers, alpha maps, holes, normals, LOD и distant terrain.
+- WMO groups, doodads, portals/rooms, indoor/outdoor state и collision.
+- M2 static/animated models, attachments, billboards, particles, ribbons и material combiners.
+- MH2O/MCLQ water, ocean, lava, slime и shore/depth behavior.
+- Sky, day/night, fog, zone lighting, weather и selective shadows.
+- World streaming, preload/retention, occlusion, render budgets и deterministic checkpoints.
+
+## Character presentation
+
+- Race/gender/body customization и character creation preview.
+- Skin/hair/face/facial hair/geosets.
+- Equipment textures, component models, enchant visuals, sheathe/unsheathe и attachments.
+- Animation selection, blending, emotes, combat, cast, death, swim, fly, mount и vehicle.
+- Creature display/model data, NPC equipment, pets, guardians и shapeshift.
+
+## Connection и world synchronization
+
+- SRP authentication, realm list, world auth, reconnect и disconnect reasons.
+- Encrypted framing, compressed packets, opcode dispatch и packet tracing.
+- Character enum/create/delete/rename/login/logout.
+- Packed GUIDs, update fields, create/update/out-of-range/destroy.
+- Movement flags, heartbeat, jump/fall/swim/fly, transports, knockback и spline movement.
+- Server time, tutorial flags, account data и feature capability detection.
+
+## Player и camera
+
+- Remappable actions вместо hardcoded keys.
+- Walk/run/backpedal/strafe/jump/fall/swim/fly и autorun.
+- Click-to-move как отдельная опциональная policy.
+- Camera orbit, zoom, collision, first-person limit и follow policies.
+- Client prediction, server correction, transport-relative movement и latency telemetry.
+- Selection, interaction range, facing и line-of-sight feedback.
+
+## Combat, spells и progression
+
+- Auto attack, attack stop, combat state, damage/heal/miss/immune feedback.
+- Spellbook, ranks, cast/channel, interruption, cooldown, global cooldown, range и resources.
+- Auras, stacks, durations, dispels, proc presentation и diminishing returns display.
+- Death, ghost, corpse, resurrection, durability и repair.
+- XP, level, rested XP, reputation, honor, arena и achievements.
+- Talents, glyphs, skills, professions, recipes и training.
+
+## Items и economy
+
+- Bags, bank, keyring, equipment, ammo, currencies и item cooldowns.
+- Loot, roll, master loot, disenchant и bind confirmations.
+- Vendors, buyback, repair, trainer и gossip services.
+- Trade, mail, auction house, guild bank и item links/tooltips.
+- Enchanting, sockets/gems, random properties и item sets.
+
+## Quests и world activities
+
+- Availability, accept, abandon, track, progress, complete и reward choice.
+- Kill, collect, interact, explore, escort, timed, reputation и spell objectives.
+- Chains, prerequisites, exclusivity, repeatable/daily/weekly и phased conditions.
+- Gossip/dialogue, scripted events, gameobjects, transports и taxi.
+- World map, minimap, exploration, POI, quest indicators и instance maps.
+
+## Groups, social и PvP
+
+- Party, raid, roles, ready check, raid targets и loot rules.
+- Friends, ignore, who, guild, channels, whispers и chat moderation feedback.
+- Duels, PvP flags, battlegrounds, arenas, scores, queues и resurrection flow.
+- LFG/Dungeon Finder, proposal, teleport, vote kick и rewards.
+
+## Instances и cinematics
+
+- Dungeon/raid entry, difficulty, lockouts, encounter states и reset.
+- Doors, triggers, boss frames, instance messages и saved state presentation.
+- Vehicles, multi-passenger seats и possession UI.
+- Cinematics, camera sequences, movies, loading screens и transitions.
+
+## UI, Lua и addons
+
+- Login, legal/realm/character creation/selection/loading screens.
+- HUD: unit frames, target/focus, action bars, buffs, cast bars, bags, quest tracking, chat и combat text.
+- FrameXML: templates, inheritance, anchors, strata, layers, scripts и events.
+- Lua 5.1-compatible API surface, secure boundaries, SavedVariables и addon lifecycle.
+- Widgets: Frame, Button, CheckButton, EditBox, Slider, StatusBar, ScrollFrame, Tooltip, Cooldown, Model, Texture, FontString, Minimap.
+- Macro conditionals, keybindings, slash commands, localization и UI scaling.
+
+## Audio
+
+- Zone/day/night music и crossfade.
+- Ambience, weather и indoor/outdoor transitions.
+- Positional world sounds, spell/combat/footstep/foley/voice и UI sounds.
+- Cache/streaming, device selection, category volumes и mute-on-focus policy.
+
+## Authoring coverage
+
+- Terrain sculpt/paint/holes/liquids и tile lifecycle.
+- M2/WMO placement, transforms, unique IDs и doodad sets.
+- Creature/gameobject templates, spawns, groups, paths и equipment.
+- Quests, gossip, conditions, loot, vendors, trainers и localization.
+- Zones, areas, graveyards, teleports, taxi, triggers и phase rules.
+- Dungeon packages, encounters, doors, bosses, scripts и validation.
+- Import, diff, package, SQL/change-set generation, dev deployment и playtest.
+
+## Требование к расширяемости
+
+Каждая функция должна быть модифицируема заменой data/config, policy или adapter до изменения core-кода. Если это невозможно, extension point и причина ограничения документируются. Пользовательские override-пакеты имеют явный приоритет, зависимости и совместимость; молчаливое изменение оригинальных данных запрещено.

docs/CONTENT_AND_SERVER_DATA.md

@@ -0,0 +1,126 @@
+# Контент, клиентские данные и серверная БД
+
+## Источник истины
+
+Пользовательские изменения хранятся в Content Project. Original client data и server DB являются импортируемыми upstream-источниками; generated cache, SQL и packages являются build artifacts.
+
+```text
+upstream snapshot + user content + build profile → validated artifacts
+```
+
+## Структура Content Project
+
+```text
+content/projects/<project>/
+  project.json
+  manifests/
+  maps/
+  placements/
+  creatures/
+  gameobjects/
+  quests/
+  dialogues/
+  loot/
+  encounters/
+  dungeons/
+  localization/
+  scripts/
+  client_assets/
+  tests/
+```
+
+Файлы должны быть детерминированными, Git-friendly, с явными `schema_version`, stable symbolic ID и минимальным шумом форматирования. Generated IDs хранятся в allocation manifest, чтобы две сборки давали одинаковый результат.
+
+## Идентификаторы и ссылки
+
+- Authoring использует symbolic ID вида `quest.my_pack.bandit_problem`.
+- Server numeric entry выделяется allocator-ом по профилю окружения.
+- WoW GUID не используется как content ID.
+- Ссылки типизированы и проверяются до сборки.
+- Удаление сущности с входящими ссылками требует явного cascade/replacement решения.
+
+## Координаты
+
+Определяются отдельные типы `CanonicalWowPosition`, `GodotWorldPosition`, `AdtTileCoordinate`, `AdtChunkCoordinate`, `LocalTilePosition`, orientation и transport-relative position.
+
+Только `CoordinateMapper` выполняет преобразования. Axis swap, origin, handedness, rotation units и scale фиксируются тестовыми golden points. Ручные преобразования в renderer, SQL exporter или gizmo запрещены.
+
+## Server snapshot
+
+Read-only import создаёт versioned snapshot с provenance:
+
+- core family и commit/revision;
+- world/auth/characters schema version;
+- время получения;
+- набор импортированных таблиц;
+- checksum и applied filters.
+
+Snapshot нужен для поиска, ссылок, offline validation и diff. Credentials и персональные данные в snapshot не включаются.
+
+## Каноническая модель и adapters
+
+Редактор работает с `QuestDefinition`, `CreatureTemplate`, `CreatureSpawn`, `GameObjectDefinition`, `LootTable`, `Dialogue`, `Condition`, `EncounterDefinition`. Адаптеры `TrinityCore335` и `AzerothCore335` отвечают за конкретные таблицы, flags, SmartAI/script conventions и capabilities.
+
+Нельзя считать близкие схемы идентичными. Перед записью adapter проверяет fingerprint схемы. Unsupported property выдаёт ошибку или documented degradation, но не игнорируется молча.
+
+## Change set
+
+Build генерирует immutable change set:
+
+- metadata и target profile;
+- preconditions;
+- ordered operations;
+- SQL preview;
+- affected entities/tables;
+- validation report;
+- rollback или описание необратимости;
+- checksum.
+
+Apply сначала выполняет dry-run на disposable/dev DB. Повторное применение должно быть idempotent либо безопасно отклоняться precondition-ом.
+
+## Клиентские данные
+
+Custom locations и mechanics могут требовать согласованных изменений:
+
+- ADT/WDT/WDL, M2/WMO/BLP;
+- DBC overlays;
+- minimap/world map assets;
+- loading screens, audio и localization;
+- server maps, collision, pathfinding/mmaps/vmaps;
+- DB records и scripts.
+
+`ContentBundleManifest` связывает client и server artifacts общей версией. Клиент не входит в мир при несовместимой обязательной версии пакета без понятной диагностики.
+
+## Overlay и модификации
+
+Оригинальные извлечённые файлы не изменяются in-place. Пользовательские пакеты образуют ordered overlay:
+
+```text
+base → core compatibility → project dependencies → user project → local dev override
+```
+
+Конфликт разрешается декларативным priority/dependency rule и показывается в build report. Для коллекций предпочтительны semantic merge operations, а не копирование целой upstream-таблицы.
+
+## Сборка и публикация
+
+Pipeline: `inspect → import → validate → compile → bake → diff → package → verify → publish`.
+
+Каждый шаг:
+
+- детерминирован при одинаковых входах;
+- кешируется по content hash;
+- пишет structured diagnostics;
+- не публикует частичный результат;
+- доступен из Godot Editor и headless CI.
+
+## Миграции форматов
+
+Каждая схема имеет monotonically increasing version. Loader либо мигрирует старую версию с backup, либо открывает read-only. Migration имеет fixture `before → after`, проверку idempotence и documented loss policy.
+
+## Локализация
+
+Текст хранится по locale, отдельно от логики. Validator проверяет placeholders, plural/gender conventions, длины UI, отсутствующие переводы и orphan keys. Fallback locale задаётся профилем и явно отображается в preview.
+
+## Пользовательские scripts
+
+Script assets имеют declared hooks, API version, permissions и deterministic validation. Генерация C++ skeleton для core допустима, но его сборка и deployment являются отдельным артефактом. Editor не обещает выразить любую серверную механику только через визуальный граф.

docs/GAME_DESIGN.md

@@ -0,0 +1,100 @@
+# Геймдизайн пользовательского контента
+
+## Цель
+
+Инструменты должны помогать создавать понятный, проверяемый и поддерживаемый контент, не навязывая автору один стиль игры. Blizzlike-параметры являются профилем по умолчанию, а не скрытым ограничением.
+
+## Карточка игровой функции
+
+Перед реализацией функции фиксируются:
+
+- целевой игрок и player goal;
+- core loop и ожидаемая длительность;
+- правила, ресурсы и серверная авторитетность;
+- affordance, feedback и failure/recovery states;
+- reward, progression и economy impact;
+- solo/group/PvP context;
+- accessibility и localization;
+- telemetry/test questions;
+- abuse/exploit risks.
+
+Настройка должна быть data-driven там, где это не нарушает безопасность и целостность сервера.
+
+## Квесты
+
+Квест описывается через intent и progression graph, а не только набор DB-полей. Проверяются:
+
+- понятная причина и цель;
+- доступность giver/ender;
+- достижимость каждого objective;
+- prerequisites, chains и mutually exclusive branches;
+- плотность целей, travel time и конкуренция игроков;
+- drop chance и ожидаемое число действий;
+- failure/retry для escort, timed и scripted objectives;
+- reward относительно уровня, сложности и экономики;
+- локализация и отсутствие противоречий текста фактическим правилам.
+
+Graph validator обнаруживает циклы без намеренного repeat policy, недостижимые узлы, отсутствующие targets и dead ends.
+
+## Локации
+
+Локация проектируется слоями:
+
+- macro navigation и landmarks;
+- безопасные маршруты и опасные зоны;
+- quest hubs и distribution целей;
+- spawn ecology и respawn pressure;
+- точки отдыха, vendors, graveyard и transport;
+- визуальная читаемость, lighting, audio и weather;
+- streaming/performance budgets;
+- boundary behavior и переходы между зонами.
+
+Редактор должен показывать heatmaps плотности spawn, quest travel paths, level/difficulty bands, line-of-sight blockers и приблизительную стоимость рендера.
+
+## Подземелья и encounters
+
+`DungeonPackage` объединяет входы, difficulty, encounters, doors, triggers, trash groups, bosses, loot, quests, graveyards, scripts и localization.
+
+Для encounter фиксируются:
+
+- learning objective и fantasy;
+- phases и transition conditions;
+- ability cadence и telegraphs;
+- positioning/movement requirements;
+- tank/healer/damage responsibilities без исключения альтернативных составов, если это цель;
+- fail states, wipe recovery и reset;
+- tuning parameters отдельно от script logic;
+- deterministic simulation cases и live playtest checklist.
+
+Сложность должна появляться из читаемых взаимодействий, а не из скрытой информации или случайной несовместимости механик.
+
+## Баланс
+
+- Формулы и tuning values версионируются отдельно от UI и scripts.
+- У каждого параметра есть unit, диапазон и rationale.
+- Нельзя балансировать только по одному идеальному сценарию; проверяются level, gear, party size и latency bands.
+- Изменение reward/economy сопровождается impact report.
+- Randomness документирует distribution, pity/guarantee policy при наличии и worst-case experience.
+
+## Feedback и UX
+
+Игрок должен понимать: что произошло, почему, что изменилось и что можно сделать дальше. Network delay не маскируется ложным успехом: pending, confirmed и rejected состояния различаются визуально.
+
+Критическая информация не должна зависеть только от цвета, звука или addon. Ошибки range, target, resource, cooldown, inventory space и prerequisites имеют специфичное сообщение.
+
+## Совместимость и модификации
+
+Автор может переопределять tuning, тексты, layouts, content graphs и presentation assets через overlay-пакеты. Изменение protocol/security/authoritative rules требует отдельного совместимого profile. Пакет объявляет зависимости, конфликты и ожидаемые core capabilities.
+
+## Playtesting
+
+Каждая feature проходит:
+
+1. content validation;
+2. designer smoke в offline preview;
+3. server-integrated functional test;
+4. exploratory playtest с заранее заданными вопросами;
+5. regression после правок;
+6. performance и multiplayer soak, если применимо.
+
+Отчёт отделяет наблюдения от интерпретаций и решений. Исправление симптома не заменяет проверку исходной design hypothesis.

docs/GODOT_EDITOR.md

@@ -0,0 +1,107 @@
+# Инструменты OpenWC внутри Godot Editor
+
+## Принцип
+
+Все интерактивные authoring-инструменты реализуются как Godot `EditorPlugin`. Отдельный native GUI не является частью целевой архитектуры. Headless-команды допускаются для CI и batch build, но используют те же application services и validators.
+
+## Workspace
+
+Плагин `addons/openwc_editor` должен предоставлять:
+
+- главное рабочее пространство World;
+- docks Content Browser, Outliner, Inspector, Validation, Build, Database и History;
+- viewport overlays и gizmos;
+- project settings для путей и dev environments;
+- command palette и контекстные действия;
+- playtest launcher.
+
+Editor UI вызывает services, а не SQL, MPQ parsers или файловую запись напрямую.
+
+## Инструменты мира
+
+- Camera/navigation и переход по map/tile/coordinates.
+- Selection, multiselect, filtering, snapping и transform gizmo.
+- Terrain sculpt: raise/lower, smooth, flatten, noise, stamp.
+- Terrain paint: texture layers, alpha, holes и liquid masks.
+- Placement: M2, WMO, creature, gameobject, trigger, sound emitter.
+- Paths: waypoint, patrol, spline, taxi и transport preview.
+- Volumes: area, subzone, encounter, graveyard, phase и weather.
+- Visualization modes: collision, normals, chunk/tile bounds, nav/pathing, spawn density, quest dependencies и streaming budgets.
+
+Каждый stroke или placement создаёт одну логическую undoable command. Длительный stroke агрегируется, чтобы history не содержала команду на каждую вершину.
+
+## Data editors
+
+- Creature и gameobject templates.
+- Spawn/group/path editor.
+- Quest form и quest-chain graph.
+- Gossip/dialogue и conditions.
+- Loot/vendor/trainer/item editors.
+- Dungeon/encounter graph.
+- Localization table с completeness report.
+- Raw server record inspector только как диагностический режим.
+
+Инспекторы генерируются из `ContentTypeDescriptor`, но сложные сущности могут иметь специализированный inspector. Валидация отображается у поля, сущности и проекта.
+
+## Selection и scene tree
+
+Authoring selection хранится отдельно от runtime scene tree. Preview-ноды считаются disposable projection: их можно пересоздать из `EditorWorldModel`. Сохранение `.tscn` не является способом записи server content.
+
+## Undo/redo и autosave
+
+- Все мутации проходят через command history.
+- Команда хранит стабильные IDs, а не ссылки на Node.
+- Autosave пишет recovery journal атомарно.
+- После crash предлагается восстановление с preview diff.
+- External file changes обнаруживаются; конфликт не перезаписывается автоматически.
+
+## Длительные задачи
+
+Import, bake, validation, packaging и DB snapshot выполняются как jobs:
+
+- progress и текущий этап;
+- cancellation token;
+- структурированные diagnostics;
+- отсутствие блокировки editor UI;
+- staging output и атомарная публикация результата;
+- повторяемая команда для headless CI.
+
+## Database dock
+
+- Показывает тип ядра, revision, schema version и capabilities.
+- По умолчанию read-only.
+- Production target визуально и технически отделён от dev.
+- Перед apply показывает SQL/change diff, preconditions и backup status.
+- Secrets не сохраняются в проект и не попадают в output/log.
+
+## Playtest
+
+Редактор должен уметь:
+
+1. проверить Content Project;
+2. собрать client assets и server change set;
+3. применить change set к disposable/dev environment;
+4. запустить или перезапустить core при необходимости;
+5. запустить клиент на нужной карте и позиции;
+6. собрать client/server logs и test observations;
+7. откатить временный change set.
+
+Fast preview без сервера допускается для геометрии, освещения, spawn layout и quest graph, но НЕ считается проверкой серверной механики.
+
+## Расширения редактора
+
+Новый тип контента регистрирует schema, icon, inspector, validator, compiler и optional viewport presenter. Плагин обязан объявить версию API и зависимости. Неизвестное поле сохраняется round-trip, если формат это допускает.
+
+## UX-принципы
+
+- Безопасные значения по умолчанию и preview перед разрушительной операцией.
+- Ошибка объясняет проблему, местоположение и действие для исправления.
+- Stable IDs видны, но пользователь в основном работает с именами и ссылками.
+- Bulk-edit показывает scope и итоговый diff.
+- Горячие клавиши переназначаются.
+- Цвет не является единственным носителем статуса.
+- Основные сценарии доступны без ручного SQL.
+
+## MVP
+
+Первый editor slice: открыть карту, импортировать server snapshot, увидеть spawns, поставить NPC, создать простой kill quest, проверить ссылки, получить SQL diff, применить к dev-базе и запустить playtest.

docs/README.md

@@ -0,0 +1,45 @@
+# OpenWC Documentation
+
+Этот каталог — единая точка входа в разработку OpenWC: клиента World of Warcraft 3.3.5a и набора инструментов авторинга внутри Godot Editor.
+
+Исполняемая последовательность текущих целей находится в [`../targets/README.md`](../targets/README.md). Все агенты обязаны следовать корневому [`../AGENTS.md`](../AGENTS.md).
+
+## Статус документов
+
+Документы описывают целевую архитектуру. Реализованное состояние рендера зафиксировано отдельно в [`../RENDER.md`](../RENDER.md). Если описание целевого решения расходится с кодом, это считается известным архитектурным долгом, а не разрешением обходить границы слоёв.
+
+Нормативные слова `ДОЛЖЕН`, `НЕ ДОЛЖЕН`, `СЛЕДУЕТ` и `МОЖЕТ` задают обязательность решения. Существенные отклонения оформляются Architecture Decision Record (ADR).
+
+## Карта документов
+
+| Документ | Назначение |
+|---|---|
+| [ARCHITECTURE.md](ARCHITECTURE.md) | Границы модулей, направления зависимостей, runtime и editor |
+| [CLIENT_FEATURES.md](CLIENT_FEATURES.md) | Полная карта функций клиента WoW 3.3.5a |
+| [GODOT_EDITOR.md](GODOT_EDITOR.md) | Архитектура инструментов внутри Godot Editor |
+| [CONTENT_AND_SERVER_DATA.md](CONTENT_AND_SERVER_DATA.md) | Content Project, данные клиента, БД TrinityCore/AzerothCore, сборка и публикация |
+| [GAME_DESIGN.md](GAME_DESIGN.md) | Принципы геймдизайна, квестов, локаций, подземелий и баланса |
+| [TESTING.md](TESTING.md) | Стратегия тестирования runtime, протокола, рендера и authoring pipeline |
+| [ROADMAP.md](ROADMAP.md) | Последовательность вертикальных срезов и критерии готовности |
+| [REFERENCES.md](REFERENCES.md) | Использованные локальные reference-проекты и правила работы с ними |
+
+## Обязательный workflow изменения функции
+
+1. Найти функцию в матрице [CLIENT_FEATURES.md](CLIENT_FEATURES.md).
+2. Определить владельца данных и границу модуля по [ARCHITECTURE.md](ARCHITECTURE.md).
+3. Для контента описать канонические данные и server adapter по [CONTENT_AND_SERVER_DATA.md](CONTENT_AND_SERVER_DATA.md).
+4. Для игровых изменений сформулировать player goal, feedback и failure states по [GAME_DESIGN.md](GAME_DESIGN.md).
+5. До реализации определить тесты и observability по [TESTING.md](TESTING.md).
+6. Выполнить работу вертикальным срезом и обновить статус feature matrix.
+
+## Definition of Done для документации
+
+Изменение считается документированным, если указаны:
+
+- владелец состояния;
+- публичные команды, события или read models;
+- формат сохранения и версия схемы, если есть данные;
+- серверная авторитетность и поведение при рассинхронизации;
+- пользовательский сценарий и обработка ошибок;
+- автоматические и ручные проверки;
+- migration/rollback для изменяемого формата или БД.

docs/REFERENCES.md

@@ -0,0 +1,59 @@
+# Локальные reference-проекты
+
+Reference-код используется для исследования форматов, поведения и архитектурных вариантов. Он не определяет API OpenWC и не копируется без проверки лицензии, корректности и соответствия Godot.
+
+## Основные источники
+
+### OpenWC renderer
+
+- [`../RENDER.md`](../RENDER.md) — фактическое состояние streaming, terrain, M2/WMO, liquids, sky, caches и performance rules.
+
+### WowUnreal
+
+- `reference/WowUnreal/specs/overview.md` — системная декомпозиция полного клиента.
+- `networking.md`, `movement.md`, `character.md`, `ui-framexml.md`, `lua-api.md`, `dbc-wrappers.md`, `audio.md`, `water.md` — полезные coverage checklists и acceptance criteria.
+
+Используем: полноту feature map и привычку задавать критерии проверки. Не переносим Unreal-specific классы и renderer assumptions.
+
+### WoWee
+
+- `reference/WoWee/docs/architecture.md` — разделение renderer/network/game/UI/pipeline.
+- `reference/WoWee/tools/editor/FORMAT_SPEC.md` — open formats, coordinates, collision, packaging и SQL export.
+- `reference/WoWee/TESTING.md` — единая точка запуска тестов, fixtures, sanitizers и CI discipline.
+- `reference/WoWee/EXPANSION_GUIDE.md` — protocol/data profile separation.
+
+Используем: детерминированные authoring formats, headless parity, adapter profiles и validation-first pipeline. Не принимаем автоматически конкретные форматы или заявленную полноту реализации.
+
+### Noggit Red
+
+- `reference/noggit-red` — UX и domain concepts специализированного world editor: terrain editing, placements, UIDs и map workflows.
+
+Используем: понимание authoring interaction и рисков unique IDs. Целевой UI реализуется только через Godot EditorPlugin API.
+
+### open-realm и whoa
+
+- `reference/open-realm/games/world-of-warcraft` — format/render pipeline и архитектурные исследования.
+- `reference/whoa` — поведение клиента 3.3.5a и test fixtures.
+
+Используем как независимую проверку binary semantics и runtime behavior.
+
+### wow.export и Blender WoW Studio
+
+Используем для сверки conversion pipeline, материалов, моделей и authoring/export edge cases. Runtime web/Blender architecture не переносится в OpenWC.
+
+## Правила исследования
+
+1. Для protocol semantics приоритет имеют wire fixtures и соответствующая версия server core.
+2. Для бинарных форматов вывод подтверждается минимум двумя независимыми источниками либо fixture-тестом.
+3. Reference implementation не считается спецификацией без проверки edge cases.
+4. Любое заимствование проверяется по лицензии и документируется.
+5. Proprietary data не переносится в fixtures или репозиторий.
+6. Вывод, влияющий на публичный контракт, оформляется ADR или обновлением соответствующей спецификации.
+
+## Замеченные полезные уроки
+
+- Полный клиент требует coverage map; иначе хорошо видимые renderer-функции вытесняют gameplay, UI и recovery paths.
+- Editor нуждается в CLI/headless parity для CI, даже если вся интерактивная работа находится в Godot.
+- Coordinate conversion и ID allocation должны быть централизованы раньше world editing.
+- DB export без canonical model быстро связывает UI с одной версией ядра.
+- Screenshot smoke полезен, но должен дополняться deterministic state, performance и protocol tests.

docs/ROADMAP.md

@@ -0,0 +1,112 @@
+# Roadmap OpenWC
+
+> Этот документ объясняет стратегию на высоком уровне. Исполняемый порядок, текущий статус, checklist и доказательства завершения ведутся только в [`../targets/README.md`](../targets/README.md). При расхождении `targets/` имеет приоритет.
+
+## Стратегия
+
+Работа идёт вертикальными срезами. Каждый срез включает data, domain, adapter, presentation, editor support, diagnostics и tests. Горизонтальная реализация всех opcodes или всех editor-панелей без пользовательского результата не считается milestone.
+
+## M0 — Архитектурный фундамент
+
+- Утвердить документы и ADR workflow.
+- Ввести module boundaries и dependency checks.
+- Выделить input, camera, movement, terrain query и character presentation из тестового контроллера.
+- Заменить зависимость streamer от Camera3D на `StreamingFocus`.
+- Зафиксировать coordinate mapper и golden points.
+
+Готово, когда render sandbox сохраняет текущее качество, а domain тестируется без scene tree.
+
+## M1 — Content Project и Editor shell
+
+- `addons/openwc_editor` с workspace и docks.
+- Content Project schema, stable IDs, save/load/migration.
+- Selection, command history, autosave/recovery.
+- Validation dock и headless validation.
+- Read-only asset/content browser.
+
+Готово, когда небольшой synthetic project можно создать, изменить, undo, перезапустить Editor и получить идентичное состояние.
+
+## M2 — Server inspector и adapters
+
+- TrinityCore/AzerothCore connection profiles.
+- Schema detection и capabilities.
+- Read-only snapshots creatures, gameobjects, spawns и quests.
+- Канонические модели, semantic diff и ID allocation.
+- SQL change-set dry-run на disposable DB.
+
+Готово, когда одна сущность round-trip проходит оба поддерживаемых adapter profile без молчаливой потери данных.
+
+## M3 — World Editor MVP
+
+- Map viewport и coordinate overlays.
+- Server spawn visualization.
+- Selection, transform gizmo, placement и paths.
+- NPC inspector, validation и undo/redo.
+- Change set и dev apply.
+
+Готово, когда NPC размещается в Editor и появляется на тестовом core в ожидаемой позиции.
+
+## M4 — Quest vertical slice
+
+- Quest form и chain graph.
+- Kill/collect/explore objectives, giver/ender, rewards и localization.
+- Dependency/reachability/economy validation.
+- Dev deploy и integrated playtest launcher.
+
+Готово, когда созданный в Editor квест полностью проходится клиентом.
+
+## M5 — Playable network client
+
+- Auth, realm, character selection и world session.
+- Entity/update fields и world spawn.
+- Movement prediction/reconciliation.
+- Basic HUD, targeting, chat и disconnect recovery.
+
+Готово, когда клиент стабильно входит в мир, перемещается и видит синхронизированные entities.
+
+## M6 — Core gameplay
+
+- Combat/spells/auras/death.
+- Inventory/equipment/loot/vendors.
+- Quest runtime и world map/minimap.
+- Character visuals и animation coverage.
+- Lua/FrameXML foundation.
+
+Готово, когда базовый leveling loop проходит без внешнего клиента.
+
+## M7 — Dungeon authoring
+
+- DungeonPackage, encounters, triggers, doors и spawn groups.
+- SmartAI/script skeleton generation.
+- Encounter graph validation и tuning profiles.
+- Group/instance/loot/lockout runtime.
+
+Готово, когда custom dungeon собирается, разворачивается и проходится группой на test core.
+
+## M8 — Compatibility и completeness
+
+- Feature matrix WoW 3.3.5a.
+- Addon compatibility tiers.
+- Social, PvP, professions, economy services, vehicles и cinematics.
+- Core revision matrix, migration и release packaging.
+- Performance, accessibility, localization и soak hardening.
+
+## Приоритет backlog
+
+При равной ценности порядок такой:
+
+1. безопасность данных и воспроизводимость;
+2. корректность протокола и authoritative state;
+3. пользовательский vertical slice;
+4. diagnostics и testability;
+5. frame pacing;
+6. визуальная точность и polish.
+
+## Не делать раньше времени
+
+- прямую запись в production DB;
+- универсальный visual scripting для любой C++ механики;
+- массовую реализацию Lua API без работающего UI slice;
+- большой rewrite существующего renderer;
+- multi-expansion abstraction до устойчивого профиля 3.3.5a;
+- proprietary asset packaging в репозитории.

docs/TESTING.md

@@ -0,0 +1,152 @@
+# Стратегия тестирования OpenWC
+
+## Принцип
+
+Тесты являются частью функционала платформы: Godot Editor должен запускать проверки, показывать diagnostics, открывать проблемную сущность и формировать воспроизводимый playtest bundle. Один ручной запуск сцены не является достаточным доказательством.
+
+## Пирамида тестов
+
+### Unit
+
+- parsers, codecs, bit/byte boundaries и malformed input;
+- coordinate transforms и math;
+- domain reducers, state machines, formulas и validators;
+- schema migrations, ID allocation и semantic diff;
+- quest/encounter graph rules;
+- material mapping helpers без GPU там, где возможно.
+
+### Contract
+
+- packet fixtures для build 12340;
+- golden update fields и packed GUID;
+- TrinityCore/AzerothCore schema fingerprints;
+- adapter round-trip `canonical → SQL → snapshot → canonical`;
+- Content Project compatibility и migration fixtures;
+- renderer/editor public API contracts.
+
+### Integration
+
+- auth/realm/world session с disposable test core;
+- character enum/login/update object/movement;
+- asset import → cache → render attach;
+- content build → SQL apply → server query;
+- Godot Editor command → undo/redo → save/reload.
+
+### End-to-end
+
+- login → character → enter world;
+- movement и server reconciliation;
+- combat/cast/aura/death;
+- quest accept/progress/complete/reward;
+- loot/inventory/vendor;
+- party/dungeon flow;
+- editor NPC + quest → deploy → playtest.
+
+### Visual и performance
+
+- deterministic screenshot checkpoints по картам, времени и погоде;
+- perceptual diff с approved baseline и tolerance;
+- frame time, hitch percentiles, draw calls, memory, descriptor count и streaming queues;
+- long traversal через ADT boundaries;
+- dense WMO/M2, water, character equipment и UI scale matrices.
+
+### Exploratory и game design
+
+- quest clarity и travel time;
+- encounter readability и recovery;
+- economy/reward impact;
+- accessibility, localization и atypical input;
+- latency/loss/reconnect behavior;
+- authoring usability и error recovery.
+
+## Test fixtures
+
+Fixtures должны быть минимальными, обезличенными и легально распространяемыми. Не коммитятся credentials, proprietary bulk assets, account data или production dumps.
+
+Типы fixtures:
+
+- synthetic binary chunks;
+- короткие redacted packet captures;
+- schema-only/disposable DB seed;
+- tiny custom content packs;
+- known coordinate points;
+- corrupt/truncated input corpus;
+- screenshot metadata без обязательного включения proprietary textures.
+
+## Test matrix
+
+Минимальные оси:
+
+- Godot/OS/rendering backend;
+- TrinityCore и AzerothCore supported revisions;
+- locale;
+- quality preset;
+- offline/online;
+- clean cache/warm cache;
+- latency, jitter, packet loss и reconnect;
+- content schema current/previous version.
+
+Полная матрица запускается периодически; pull request использует risk-based subset.
+
+## Godot Editor Test Center
+
+Editor dock должен предоставлять:
+
+- Validate Selection, Map, Package и Project;
+- список severity/code/location/fix suggestion;
+- переход к объекту, полю или viewport position;
+- фильтр и baseline известных diagnostics;
+- запуск headless test suites;
+- playtest checklist и запись результата;
+- экспорт machine-readable report для CI.
+
+Quick Fix допускается только как undoable command с preview diff.
+
+## Network verification
+
+- Каждый codec проверяет exact bytes и round-trip.
+- Parser никогда не читает за packet boundary.
+- Unknown opcode логируется rate-limited и не разрушает session без policy.
+- Replay отделён от transport и детерминирован.
+- Fuzz/property tests покрывают lengths, masks, packed values, compression и fragmentation.
+- Secrets/session keys не появляются в обычных логах.
+
+## Server data verification
+
+Перед apply обязательны schema capability check, foreign references, ID collisions, dry-run и backup/checkpoint. После apply выполняются targeted queries и optional core startup smoke. Rollback тестируется на disposable DB.
+
+## Content validation levels
+
+- Error: сборка или применение запрещены.
+- Warning: допустимо после осознанного подтверждения.
+- Info: рекомендация или стоимость.
+
+Примеры errors: broken reference, incompatible schema, duplicate allocation, invalid coordinate, unreachable mandatory quest step. Warnings: отсутствующий optional locale, высокая spawn density, превышение render budget.
+
+## Observability
+
+Логи структурированы по subsystem/category/correlation ID. Метрики включают network queues, entity counts, reconciliation errors, asset cache hit rate, editor job durations и validation counts. Пользовательские тексты, credentials и packet payload не логируются по умолчанию.
+
+## CI gates
+
+Изменение не сливается, если не проходят:
+
+- headless project load;
+- unit/contract tests затронутых модулей;
+- content schema validation;
+- deterministic generated artifact check;
+- renderer material smoke при изменении renderer;
+- adapter dry-run при изменении server mapping;
+- documentation link check.
+
+Nightly дополнительно запускает core integration, packet replay corpus, visual checkpoints, traversal performance и migration matrix.
+
+## Definition of Done функции
+
+- acceptance criteria наблюдаемы;
+- happy path и минимум один failure/recovery path автоматизированы;
+- boundary и malformed cases проверены для parser/network/data;
+- diagnostics ведут к проблемному объекту;
+- performance budget указан для frame-critical функции;
+- manual playtest имеет сценарий и ожидаемый результат;
+- regression test воспроизводит исправленный дефект.