обновление md файлов
This commit is contained in:
@@ -56,6 +56,8 @@ Renderer получает `StreamingFocus`, `WorldVisualSnapshot` и presentatio
|
||||
|
||||
Владеет 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 напрямую.
|
||||
@@ -86,6 +88,12 @@ Godot `EditorPlugin` регистрирует workspace, docks, inspectors, gizm
|
||||
|
||||
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
|
||||
@@ -129,6 +137,7 @@ src/
|
||||
editor/
|
||||
server_data/
|
||||
build_pipeline/
|
||||
navigation/
|
||||
shared/
|
||||
tests/
|
||||
addons/
|
||||
|
||||
@@ -92,6 +92,7 @@
|
||||
- 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.
|
||||
- Заменяемый Lua 5.1.1 backend; `rilua` и PUC-Rio проходят единый WoW-specific compatibility corpus до выбора production VM.
|
||||
- Widgets: Frame, Button, CheckButton, EditBox, Slider, StatusBar, ScrollFrame, Tooltip, Cooldown, Model, Texture, FontString, Minimap.
|
||||
- Macro conditionals, keybindings, slash commands, localization и UI scaling.
|
||||
|
||||
@@ -110,6 +111,7 @@
|
||||
- Quests, gossip, conditions, loot, vendors, trainers и localization.
|
||||
- Zones, areas, graveyards, teleports, taxi, triggers и phase rules.
|
||||
- Dungeon packages, encounters, doors, bosses, scripts и validation.
|
||||
- Navigation authoring: walkability overlay, reachability, patrol/escort validation, off-mesh links и dynamic doors; optional `recast-rs` backend.
|
||||
- Import, diff, package, SQL/change-set generation, dev deployment и playtest.
|
||||
|
||||
## Требование к расширяемости
|
||||
|
||||
@@ -91,6 +91,15 @@ Custom locations и mechanics могут требовать согласован
|
||||
|
||||
`ContentBundleManifest` связывает client и server artifacts общей версией. Клиент не входит в мир при несовместимой обязательной версии пакета без понятной диагностики.
|
||||
|
||||
## Navigation artifacts
|
||||
|
||||
Content Project хранит navigation profile и authoring hints, но не generated navmesh tiles. Build pipeline может создать:
|
||||
|
||||
- OpenWC navigation cache через pinned `recast-rs` для Editor preview и validation;
|
||||
- server mmap artifact через отдельный TrinityCore/AzerothCore-compatible exporter, когда его совместимость доказана.
|
||||
|
||||
Артефакты имеют разные type/version IDs и не подменяют друг друга. Manifest фиксирует source geometry hash, coordinate profile, backend/version, Recast parameters и tile checksums. Любое изменение этих входов инвалидирует cache.
|
||||
|
||||
## Overlay и модификации
|
||||
|
||||
Оригинальные извлечённые файлы не изменяются in-place. Пользовательские пакеты образуют ordered overlay:
|
||||
|
||||
@@ -36,6 +36,8 @@
|
||||
|
||||
Graph validator обнаруживает циклы без намеренного repeat policy, недостижимые узлы, отсутствующие targets и dead ends.
|
||||
|
||||
Spatial validator на основе navigation backend (первоначально optional `recast-rs`) отдельно проверяет физическую достижимость giver, objectives и turn-in для заявленного movement profile. Результат является authoring diagnostic: он не заменяет server pathfinding и требует server-integrated playtest для окончательного подтверждения.
|
||||
|
||||
## Локации
|
||||
|
||||
Локация проектируется слоями:
|
||||
@@ -51,6 +53,8 @@ Graph validator обнаруживает циклы без намеренног
|
||||
|
||||
Редактор должен показывать heatmaps плотности spawn, quest travel paths, level/difficulty bands, line-of-sight blockers и приблизительную стоимость рендера.
|
||||
|
||||
Для подземелий navigation graph должен проверять связность входа, encounter rooms, дверей, recovery route и graveyard. Dynamic obstacles и off-mesh connections описываются явно, чтобы закрытая дверь или специальный переход не давали ложный положительный результат.
|
||||
|
||||
## Подземелья и encounters
|
||||
|
||||
`DungeonPackage` объединяет входы, difficulty, encounters, doors, triggers, trash groups, bosses, loot, quests, graveyards, scripts и localization.
|
||||
|
||||
@@ -27,6 +27,7 @@ Editor UI вызывает services, а не SQL, MPQ parsers или файло
|
||||
- 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.
|
||||
- Navigation overlay: walkable areas, isolated regions, off-mesh connections, path cost и unreachable selection.
|
||||
|
||||
Каждый stroke или placement создаёт одну логическую undoable command. Длительный stroke агрегируется, чтобы history не содержала команду на каждую вершину.
|
||||
|
||||
@@ -66,6 +67,20 @@ Import, bake, validation, packaging и DB snapshot выполняются как
|
||||
- staging output и атомарная публикация результата;
|
||||
- повторяемая команда для headless CI.
|
||||
|
||||
Navmesh bake через `recast-rs` оформляется таким же cancellable job: Editor экспортирует каноническую triangle geometry во staging, запускает pinned CLI/backend, импортирует versioned navigation artifact и показывает diagnostics. Preview-ноды navmesh не сохраняются как источник истины.
|
||||
|
||||
## Navigation validation
|
||||
|
||||
Первый navigation backend — optional `recast-rs`. Он используется для:
|
||||
|
||||
- проверки пути от quest giver к objectives и turn-in;
|
||||
- поиска NPC/gameobject вне walkable polygon;
|
||||
- проверки patrol/escort paths;
|
||||
- проверки связности входов, дверей и encounter rooms;
|
||||
- визуализации area costs, holes и off-mesh connections.
|
||||
|
||||
Профиль bake хранит версию backend и параметры agent radius/height/climb, cell size/height, slope, region и tile size. Изменение профиля инвалидирует navigation cache. Отсутствие backend не должно мешать редактированию, но navigation-dependent validation помечается как `Not run`.
|
||||
|
||||
## Database dock
|
||||
|
||||
- Показывает тип ядра, revision, schema version и capabilities.
|
||||
|
||||
@@ -22,6 +22,7 @@
|
||||
| [TESTING.md](TESTING.md) | Стратегия тестирования runtime, протокола, рендера и authoring pipeline |
|
||||
| [ROADMAP.md](ROADMAP.md) | Последовательность вертикальных срезов и критерии готовности |
|
||||
| [REFERENCES.md](REFERENCES.md) | Использованные локальные reference-проекты и правила работы с ними |
|
||||
| [TOOLING_CATALOG.md](TOOLING_CATALOG.md) | Реестр готовых библиотек, редакторов, test oracles и кандидатов на интеграцию |
|
||||
|
||||
## Обязательный workflow изменения функции
|
||||
|
||||
|
||||
@@ -41,6 +41,32 @@ Reference-код используется для исследования фор
|
||||
|
||||
Используем для сверки conversion pipeline, материалов, моделей и authoring/export edge cases. Runtime web/Blender architecture не переносится в OpenWC.
|
||||
|
||||
### Wowser
|
||||
|
||||
- [`wowserhq/wowser`](https://github.com/wowserhq/wowser) — MIT proof-of-concept браузерного клиента WoW 3.3.5a.
|
||||
- [`wowserhq/client`](https://github.com/wowserhq/client) — выделенный web client.
|
||||
- [`wowserhq/pipeline`](https://github.com/wowserhq/pipeline) — asset delivery pipeline.
|
||||
|
||||
Используем как независимый reference для auth → realm → character → world lifecycle, SRP/cryptography, binary packet handling, asset delivery и частичного terrain/model renderer. Особенно полезен для поиска уже разобранных 3.3.5a packet/data edge cases и идей test fixtures.
|
||||
|
||||
Не переносим напрямую старый browser stack, WebSocket proxy, React/Three.js abstractions или pipeline server. Заявленное поведение проверяем по TrinityCore/AzerothCore и оригинальному клиенту; proof-of-concept не является спецификацией полноты.
|
||||
|
||||
### recast-rs
|
||||
|
||||
- [`wowemulation-dev/recast-rs`](https://github.com/wowemulation-dev/recast-rs) — Rust-порт Recast/Detour: navmesh generation, tiled pathfinding, spatial queries, crowd simulation и dynamic obstacles.
|
||||
|
||||
Планируем использовать как optional offline navigation backend для Godot Editor: визуализация walkability, проверка достижимости quest/encounter targets, patrol paths и dungeon topology. Начальная интеграция выполняется через CLI/build job, а не через renderer или gameplay runtime.
|
||||
|
||||
Важно: принадлежность к WoW emulation ecosystem не доказывает совместимость с форматами TrinityCore/AzerothCore `.mmap/.mmtile`. Генерация server mmaps разрешается только после отдельного compatibility spike с exact parameter, coordinate, tile и binary/behavior comparison. До этого OpenWC navigation cache и server mmaps считаются разными артефактами.
|
||||
|
||||
### rilua
|
||||
|
||||
- [`wowemulation-dev/rilua`](https://github.com/wowemulation-dev/rilua) — написанная на Rust реализация Lua 5.1.1 с embedding API, bytecode, официальным Lua test corpus, fuzzing и oracle comparison с PUC-Rio.
|
||||
|
||||
Рассматриваем одновременно как кандидата на addon Lua runtime и как headless test oracle. TOC loader, FrameXML, WoW API, events, SavedVariables и secure execution остаются слоями OpenWC. Критический gap — отсутствие готовой WoW taint system; C ABI также намеренно не совместим с PUC-Rio. Production-решение принимается только после сравнения `rilua`, PUC-Rio 5.1.1 и оригинального клиента на WoW-specific corpus.
|
||||
|
||||
Подробные статусы и evaluation cards ведутся в [`TOOLING_CATALOG.md`](TOOLING_CATALOG.md).
|
||||
|
||||
## Правила исследования
|
||||
|
||||
1. Для protocol semantics приоритет имеют wire fixtures и соответствующая версия server core.
|
||||
@@ -49,6 +75,7 @@ Reference-код используется для исследования фор
|
||||
4. Любое заимствование проверяется по лицензии и документируется.
|
||||
5. Proprietary data не переносится в fixtures или репозиторий.
|
||||
6. Вывод, влияющий на публичный контракт, оформляется ADR или обновлением соответствующей спецификации.
|
||||
7. Перед собственной реализацией сложной подсистемы проверить [`TOOLING_CATALOG.md`](TOOLING_CATALOG.md) и добавить найденные решения, даже если они останутся только reference.
|
||||
|
||||
## Замеченные полезные уроки
|
||||
|
||||
@@ -57,3 +84,5 @@ Reference-код используется для исследования фор
|
||||
- Coordinate conversion и ID allocation должны быть централизованы раньше world editing.
|
||||
- DB export без canonical model быстро связывает UI с одной версией ядра.
|
||||
- Screenshot smoke полезен, но должен дополняться deterministic state, performance и protocol tests.
|
||||
- Navmesh-библиотека полезна для authoring validation, но не должна становиться источником authoritative NPC movement на клиенте.
|
||||
- Готовая Lua VM сокращает объём работы только на уровне языка; WoW API, FrameXML, addon lifecycle, secure actions и taint всё равно требуют отдельной fidelity-программы.
|
||||
|
||||
@@ -23,6 +23,9 @@
|
||||
- adapter round-trip `canonical → SQL → snapshot → canonical`;
|
||||
- Content Project compatibility и migration fixtures;
|
||||
- renderer/editor public API contracts.
|
||||
- `recast-rs` navigation fixtures: geometry/profile → region/poly/detail counts и path queries.
|
||||
- Lua VM contract: общий WoW-specific corpus выполняется на `rilua`, PUC-Rio 5.1.1 и, где возможно, оригинальном клиенте 3.3.5a.
|
||||
- Wowser используется как дополнительный независимый источник auth/world packet cases; fixtures принимаются только после проверки build 12340 semantics и удаления credentials/proprietary payload data.
|
||||
|
||||
### Integration
|
||||
|
||||
@@ -49,6 +52,25 @@
|
||||
- frame time, hitch percentiles, draw calls, memory, descriptor count и streaming queues;
|
||||
- long traversal через ADT boundaries;
|
||||
- dense WMO/M2, water, character equipment и UI scale matrices.
|
||||
- navmesh overlay checkpoints и bake/query budgets для больших tiles/dungeons.
|
||||
|
||||
### Navigation compatibility
|
||||
|
||||
- Golden synthetic meshes проверяют slope, climb, radius erosion, holes, tiled seams и off-mesh connections.
|
||||
- WoW fixtures проверяют canonical coordinates и ADT/WMO collision composition.
|
||||
- `recast-rs` version и bake profile закрепляются в manifest; обновление требует baseline diff.
|
||||
- OpenWC navigation cache сравнивается с C++ Recast reference на выбранных fixtures.
|
||||
- Заявление о server mmap support требует отдельного сравнения с TrinityCore/AzerothCore generator: параметры, tile bounds, polygon queries и фактическое движение существ на disposable core.
|
||||
- Editor reachability diagnostics должны различать `Reachable`, `Unreachable`, `Unknown` и `Not run`.
|
||||
|
||||
### Lua и addon compatibility
|
||||
|
||||
- Official Lua 5.1.1 suite запускается на pinned VM revision.
|
||||
- Oracle tests сравнивают results, errors, byte strings, number formatting, coroutines, metatables, GC-visible behavior и bytecode expectations.
|
||||
- WoW corpus проверяет restricted stdlib, global aliases, `bit`, BOM, GC defaults и запрещённые filesystem/native-module операции.
|
||||
- TOC/load order, FrameXML inheritance, events, SavedVariables и addon errors проверяются отдельно от VM.
|
||||
- Secure actions, combat lockdown и taint propagation имеют обязательные negative tests; без них addon compatibility не получает статус `Verified`.
|
||||
- Performance suite измеряет `OnUpdate`, event fan-out, table churn, allocation и incremental GC frame budget.
|
||||
|
||||
### Exploratory и game design
|
||||
|
||||
|
||||
@@ -0,0 +1,91 @@
|
||||
# Каталог готовых инструментов и reference-решений
|
||||
|
||||
## Назначение
|
||||
|
||||
OpenWC следует принципу `research before build`: перед реализацией сложной подсистемы сначала ищется существующая библиотека, эмулятор, редактор, specification или test corpus. Цель — быстрее находить проверенные решения, сравнивать независимые реализации и не повторять уже проделанную работу.
|
||||
|
||||
Каталог не является списком автоматически одобренных dependencies. Любой кандидат проходит проверку лицензии, зрелости, fidelity, безопасности, производительности, поддержки платформ и стоимости интеграции.
|
||||
|
||||
## Статусы
|
||||
|
||||
- `REFERENCE` — источник идей, поведения, форматов или тестов; код не подключён.
|
||||
- `CANDIDATE` — возможная dependency; требуется compatibility spike.
|
||||
- `EVALUATING` — выполняется spike с зафиксированными критериями.
|
||||
- `ADOPTED` — закреплены версия, boundary, лицензия, tests и update policy.
|
||||
- `REJECTED` — не подходит; причина сохраняется, чтобы не повторять исследование.
|
||||
- `REPLACE` — используется временно и имеет согласованный план замены.
|
||||
|
||||
## Обязательная карточка кандидата
|
||||
|
||||
```text
|
||||
Name / URL:
|
||||
Status:
|
||||
Problem solved:
|
||||
Planned boundary:
|
||||
License:
|
||||
Platforms/toolchain:
|
||||
Fidelity evidence:
|
||||
Known gaps:
|
||||
Security/data risks:
|
||||
Performance evidence:
|
||||
Spike and acceptance criteria:
|
||||
Pinned version/update policy:
|
||||
Decision/ADR:
|
||||
```
|
||||
|
||||
## Реестр
|
||||
|
||||
| Инструмент | Статус | Область | Планируемое использование | Главный риск |
|
||||
|---|---|---|---|---|
|
||||
| OpenWC native loaders | ADOPTED | MPQ/BLP/ADT/WDT/M2/WMO | Текущий import/render pipeline | Неполная fidelity форматов |
|
||||
| StormLib | ADOPTED | MPQ | Чтение архивов через native extension | Version/license/update audit |
|
||||
| WowUnreal | REFERENCE | Полный клиент | Coverage, acceptance criteria, networking/UI research | Unreal-specific design |
|
||||
| WoWee | REFERENCE | Клиент/editor/formats | Architecture, editor workflows, tests, open formats | Заявления требуют независимой проверки |
|
||||
| Noggit Red | REFERENCE | World editor | Terrain/placement UX, UID workflows | Не Godot architecture |
|
||||
| open-realm | REFERENCE | Formats/runtime | Независимая проверка parsers/render behavior | Другая архитектура и coverage |
|
||||
| whoa | REFERENCE | Client behavior | 3.3.5a runtime semantics и fixtures | Лицензия и переносимость отдельных решений |
|
||||
| wow.export | REFERENCE | Asset conversion | M2/WMO/material/export edge cases | Web-specific pipeline |
|
||||
| Blender WoW Studio | REFERENCE | Authoring/conversion | WMO/M2/ADT authoring knowledge | Blender-specific UI/data model |
|
||||
| [Wowser](https://github.com/wowserhq/wowser) | REFERENCE | 3.3.5a web client | Auth/realm/character/world protocol, binary parsing, asset pipeline и render research | Старый JS/WebGL proof-of-concept, неполный клиент |
|
||||
| [recast-rs](https://github.com/wowemulation-dev/recast-rs) | CANDIDATE | Navigation | Offline navmesh, reachability и dungeon validation | Server mmap compatibility не доказана |
|
||||
| [rilua](https://github.com/wowemulation-dev/rilua) | CANDIDATE | Lua/addons | Lua 5.1.1 runtime candidate и headless compatibility oracle | Taint/WoW API/FrameXML отсутствуют; Rust bridge |
|
||||
| PUC-Rio Lua 5.1.1 | CANDIDATE | Lua reference/runtime | Authoritative Lua oracle и альтернативный embedded VM | Нужны WoW sandbox, taint и безопасный C++ boundary |
|
||||
|
||||
## rilua — карточка кандидата
|
||||
|
||||
- **Problem solved:** Lua 5.1.1 VM, bytecode, embedding и официальный compatibility corpus для addon runtime.
|
||||
- **Planned boundary:** реализация внутреннего `LuaRuntime` interface; FrameXML, TOC, WoW API, events и SavedVariables остаются независимыми слоями OpenWC.
|
||||
- **License:** MIT OR Apache-2.0.
|
||||
- **Fidelity evidence:** официальный Lua 5.1.1 test suite и oracle comparison с PUC-Rio по заявлениям проекта; OpenWC обязан повторить проверки на pinned revision.
|
||||
- **Known gaps:** WoW taint/secure execution заявлен как post-1.0; TOC, WoW API stubs и UI находятся вне scope; C ABI не совместим с `lua_State*`; требуется измерение GC/OnUpdate performance.
|
||||
- **Spike:** сравнить `rilua`, PUC-Rio 5.1.1 и оригинальный клиент на WoW-specific corpus; проверить restricted stdlib, globals, `bit`, errors, coroutines, byte strings, GC defaults, addon load и SavedVariables.
|
||||
- **Decision policy:** не связывать UI с Rust types и не объявлять addon parity до secure/taint и FrameXML/API tests.
|
||||
|
||||
## Wowser — карточка референса
|
||||
|
||||
- **Problem studied:** полный путь клиента WoW 3.3.5a в браузере: получение assets, auth/realm/world connections, cryptography, binary packets, workers, audio и WebGL rendering.
|
||||
- **Useful repositories:** [`wowserhq/wowser`](https://github.com/wowserhq/wowser), выделенные [`wowserhq/client`](https://github.com/wowserhq/client) и [`wowserhq/pipeline`](https://github.com/wowserhq/pipeline).
|
||||
- **License:** MIT для основного репозитория; лицензии выделенных репозиториев проверяются отдельно перед переносом кода.
|
||||
- **Fidelity evidence:** заявлена поддержка только WotLK 3.3.5a; реализованы username/password auth, realm list/connection, character list, world join и packet logging. Любая packet semantics всё равно сверяется с server core и fixtures.
|
||||
- **Useful boundaries:** разделение client и asset pipeline, async/background resource work, typed binary handling, protocol lifecycle и независимый WebGL renderer.
|
||||
- **Known gaps:** proof-of-concept, неполный gameplay/UI, browser WebSocket proxy вместо native TCP, устаревший JS ecosystem (React 0.14/Three.js 0.77 era), архитектура не переносится напрямую в Godot.
|
||||
- **Decision policy:** использовать для cross-check и test ideas; не добавлять Node/Web dependencies и не копировать browser-specific abstractions в OpenWC.
|
||||
|
||||
## recast-rs — карточка кандидата
|
||||
|
||||
- **Problem solved:** Recast navmesh generation, Detour queries, tiled navigation и dynamic obstacles.
|
||||
- **Planned boundary:** offline CLI/build job и versioned OpenWC navigation artifact.
|
||||
- **License:** MIT OR Apache-2.0.
|
||||
- **Known gaps:** совместимость `.mmap/.mmtile` и параметров TrinityCore/AzerothCore не доказана.
|
||||
- **Spike:** synthetic + one WoW tile comparison с C++ Recast; затем отдельный server mmap compatibility experiment.
|
||||
|
||||
## Процесс добавления инструмента
|
||||
|
||||
1. Добавить карточку со статусом `REFERENCE` или `CANDIDATE`.
|
||||
2. Указать конкретную проблему и boundary; «полезная библиотека» недостаточно.
|
||||
3. Проверить лицензию и возможность распространения.
|
||||
4. Создать bounded spike в соответствующем target, не меняя текущую цель без указания пользователя.
|
||||
5. Собрать fixtures и сравнить с исходным поведением WoW 3.3.5a или authoritative implementation.
|
||||
6. После решения обновить статус, pinned version, ADR и regression tests.
|
||||
|
||||
Вендорить или добавлять submodule до статуса `ADOPTED` не следует. Для быстро меняющихся проектов pinned commit обязателен.
|
||||
Reference in New Issue
Block a user