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

2026-07-10 10:28:37 +04:00
parent f561e52aa9
commit 93bfe114c0
46 changed files with 2826 additions and 55 deletions
@@ -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.