актуализация референсов

.gitmodules

@@ -5,3 +5,27 @@
 	path = third_party/godot-cpp
 	url = https://github.com/godotengine/godot-cpp
 	branch = 4.5
+[submodule "reference/open-realm"]
+	path = reference/open-realm
+	url = https://github.com/corepunch/open-realm.git
+	branch = main
+[submodule "reference/whoa"]
+	path = reference/whoa
+	url = https://github.com/whoahq/whoa
+	branch = master
+[submodule "reference/WoWee"]
+	path = reference/WoWee
+	url = https://github.com/Kelsidavis/WoWee.git
+	branch = master
+[submodule "reference/WowUnreal"]
+	path = reference/WowUnreal
+	url = https://github.com/Clancey/WowUnreal
+	branch = main
+[submodule "reference/wow.export"]
+	path = reference/wow.export
+	url = https://github.com/Kruithne/wow.export.git
+	branch = main
+[submodule "reference/blender-wow-studio/pywowlib"]
+	path = reference/blender-wow-studio-3.4-1.1.0_Experimental/io_scene_wmo/pywowlib
+	url = https://github.com/wowdev/pywowlib.git
+	branch = master

RENDER.md

@@ -686,6 +686,22 @@ SKYBOX_MODEL ...
 - полноценный liquid rendering там не реализован;
 - skybox/liquid не стоит напрямую переносить как готовый код.
 
+По Benilla (pinned research commit
+`9f3de200fb4a239809acd3641671d63146098a91`):
+
+- полезна граница `world renderer -> asset/formats` без зависимости от game/UI;
+- M2 animation разделяет selection policy и renderer machinery: pose sampling,
+  parent-order composition, global sequences, billboard replacement, attachment
+  anchors и palette upload;
+- particles и ribbons симулируются на CPU для temporal fidelity, но записывают
+  геометрию в один shared effect vertex/index stream с сортировкой, batching и
+  camera-relative upload вместо отдельных dynamic Mesh/Material на emitter;
+- WMO portal flood, material pass ordering, fog/blend policy, effect lifecycle и
+  corpus/probe tooling являются полезными sources для M04 fixtures;
+- это Vanilla 1.12.1/Bevy reference, не build-12340 oracle: record layouts,
+  shader flags, effect timing и performance должны быть повторно проверены в
+  Godot против оригинального WoW 3.3.5a.
+
 По WoW 3.3.5a:
 
 - старый клиент не рендерил все как modern physically based renderer;

docs/REFERENCES.md

@@ -2,6 +2,11 @@
 
 Reference-код используется для исследования форматов, поведения и архитектурных вариантов. Он не определяет API OpenWC и не копируется без проверки лицензии, корректности и соответствия Godot.
 
+Актуальные branches и pinned commits локальных Git-референсов зафиксированы в
+[`reference/README.md`](../reference/README.md#git-reference-revisions). Gitlinks
+точно фиксируют ревизию, а `.gitmodules` задаёт canonical remote и ветку
+для контролируемого обновления.
+
 ## Основные источники
 
 ### OpenWC renderer
@@ -51,6 +56,14 @@ Reference-код используется для исследования фор
 
 Не переносим напрямую старый browser stack, WebSocket proxy, React/Three.js abstractions или pipeline server. Заявленное поведение проверяем по TrinityCore/AzerothCore и оригинальному клиенту; proof-of-concept не является спецификацией полноты.
 
+### Benilla
+
+- [`samwhosung/benilla`](https://github.com/samwhosung/benilla) — независимый клиент WoW 1.12.1 build 5875 на Rust/Bevy; исследование OpenWC зафиксировано на commit `9f3de200fb4a239809acd3641671d63146098a91`.
+- Renderer references: M2 pose/palette animation, global sequences, material/pass ordering, общий dynamic-effect stream, particles, model particles, ribbons, WMO portal visibility, lighting, sky/weather и streaming.
+- UI references: отдельный engine-free TOC/FrameXML/Lua core, template/layout/widget model, deterministic event/`OnUpdate` ordering, legacy+modern handler arguments, sandbox, SavedVariables и большой набор compatibility tests.
+
+Используем decomposition, algorithms, diagnostics и test ideas. Не переносим Bevy/ECS architecture и не считаем Vanilla behavior доказательством WotLK: M2/DBC/layout/API/security differences повторно проверяются по WoW 3.3.5a build 12340. Benilla пока не является oracle для third-party addons или secure/taint semantics; его Lua 5.1 runtime содержит compatibility work для Lua 5.0 target. Полная evaluation card находится в [`TOOLING_CATALOG.md`](TOOLING_CATALOG.md#benilla--карточка-референса).
+
 ### 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.

docs/TOOLING_CATALOG.md

@@ -48,6 +48,7 @@ Decision/ADR:
 | 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, неполный клиент |
+| [Benilla](https://github.com/samwhosung/benilla) | REFERENCE | WoW 1.12.1 client/render/UI | M2 GPU animation, materials, particles/ribbons, WMO portals, FrameXML/Lua architecture и compatibility-test ideas | Vanilla build 5875 и Bevy-specific implementation не доказывают WotLK build-12340 fidelity |
 | [warcraft-rs](https://github.com/wowemulation-dev/warcraft-rs) | CANDIDATE | WoW formats/CLI | Independent MPQ/DBC/BLP/ADT/WDT/WDL/M2/WMO validation и conversion oracle | Rust/tool duplication; claims require fixtures |
 | [WoWDBDefs](https://github.com/wowdev/WoWDBDefs) | REFERENCE | Client DB schemas | Versioned DBC definitions и typed-code generation input | Definitions still require build-specific validation |
 | [wow_dbc](https://github.com/gtker/wow_dbc) | REFERENCE | DBC | 1.12/2.4.3/3.3.5 read/write и SQLite conversion ideas | Older release, Rust integration unnecessary by default |
@@ -78,6 +79,25 @@ Decision/ADR:
 - **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.
 
+## Benilla — карточка референса
+
+- **Name / URL:** [samwhosung/benilla](https://github.com/samwhosung/benilla).
+- **Status:** `REFERENCE`; код не подключён как dependency и не вендорится.
+- **Pinned research revision:** `9f3de200fb4a239809acd3641671d63146098a91` (проверен 2026-08-12). Репозиторий публикуется автором как squashed snapshots из private tree, поэтому при повторном исследовании revision фиксируется заново.
+- **Problem studied:** полный независимый клиент WoW 1.12.1 build 5875 на Rust/Bevy, включая streamed world renderer, M2 animation/materials, WMO portal visibility, liquids/sky/weather, particles/ribbons/spell visuals и собственный TOC/FrameXML/Lua UI runtime.
+- **Planned boundary:** использовать только как независимый источник алгоритмов, decomposition, diagnostics и test cases. OpenWC сохраняет свои `WorldRenderFacade`, Godot main-thread/finalization boundaries, `LuaRuntime`, immutable UI view models/intents и build-12340 contracts; прямой Bevy/ECS или Rust-type bridge не вводится.
+- **Useful renderer source map:** `crates/benilla-world/src/model_render*`, `rig_anim*`, `rig_palette*`, `particles*`, `ribbons.rs`, `wmo_portal*`, `lighting*`, `weather*`, `terrain_stream*` и `shaders/wow_effect.wgsl`; format-side M2 animation/particle/ribbon tracks находятся в `crates/benilla-formats/src/models/anim.rs`, `particles.rs` и `ribbons.rs`.
+- **Useful UI/Lua source map:** engine-free crate `crates/benilla-ui`: `toc.rs`, `framexml.rs`, `loader/*`, `layout.rs`, `widget/*`, `order.rs`, `script/event.rs`, `script/tick.rs`, `script/saved.rs`, sandbox/stdlib bindings и compatibility tests. Особенно полезны сохранение document/load order, bottom-up `OnLoad`, nested-safe restore legacy globals `this/event/argN`, deterministic event/`OnUpdate` order и разделение plain host state от engine adapter.
+- **License:** `MIT OR Apache-2.0`; конкретное заимствование кода требует сохранения license/attribution и отдельной проверки совместимости с лицензиями OpenWC и third-party dependencies.
+- **Platforms/toolchain:** stable Rust, Bevy `0.18.1`, `mlua 0.11` с vendored Lua 5.1 и локальным `lua-src` patch pipeline. Это research stack, не предлагаемый OpenWC toolchain.
+- **Fidelity evidence:** исходники содержат подробные build-5875 byte-law annotations, corpus tests, parser fixtures и temporal/render probes. Сам приватный reverse-engineering corpus не входит в repository, а опубликованный код ориентирован на Vanilla 1.12.1, поэтому ни один его результат сам по себе не является evidence для WoW 3.3.5a build 12340.
+- **Known gaps:** README прямо ограничивает Lua built-in UI и пока не заявляет third-party addon support; taint/secure execution отсутствуют; runtime использует Lua 5.1 с точечными Lua-5.0 compatibility patches для Vanilla; renderer и scheduling зависят от Bevy render phases/ECS. Layouts, M2 records, shader flags, spell visuals, UI API и security semantics должны повторно проверяться для WotLK.
+- **Security/data risks:** Lua sandbox удаляет filesystem/OS/package/debug/native reach и принимает только text chunks, но без taint/protected-action модели этого недостаточно для 3.3.5a addons. Proprietary client assets и private RE artifacts не копируются; тесты OpenWC используют легально полученные локальные data и разрешённые metadata/fixtures.
+- **Performance evidence:** Benilla документирует collapsed rig pose/palette arrays вместо десятков тысяч bone entities и один shared effect vertex/index stream вместо per-emitter dynamic meshes; source comments приводят локальные measurements (включая около 145 mesh changes/frame до shared stream). Эти числа не воспроизведены на Godot и служат только гипотезой для bounded spike.
+- **Spike and acceptance criteria:** (1) renderer — на build-12340 M2 fixtures сравнить bone palette/global sequences, material ordering, particle plane/sphere/spline emitters, head/tail/model particles и ribbons по phase/duration/lifetime; затем проверить Godot-friendly shared effect buffer/pool без нарушения M03 budgets; (2) UI — прогнать WotLK TOC/FrameXML/Lua corpus на document order, inheritance, anchors, handler calling convention, event order, `OnUpdate`, SavedVariables, restricted libraries и error text; secure actions/taint имеют отдельный обязательный corpus. Любое принятое решение требует original-client paired evidence, p50/p95/p99 и regression fixtures.
+- **Pinned version/update policy:** исследование и ссылки привязаны к указанному commit. Обновление проводится вручную по diff релевантных directories; moving `main` не становится новым oracle автоматически.
+- **Decision / ADR:** `REFERENCE`, не dependency. ADR требуется только если Benilla-inspired решение меняет публичный renderer/effects/UI/Lua contract, cache/schema, engine boundary или добавляет dependency.
+
 ## recast-rs — карточка кандидата
 
 - **Problem solved:** Recast navmesh generation, Detour queries, tiled navigation и dynamic obstacles.

reference/README.md

@@ -6,6 +6,28 @@ Godot project scanning is disabled for this directory by `.gdignore`. Reference
 assets remain available to Git, text search and external tooling, but Godot must
 not generate `.import` sidecars inside nested reference repositories.
 
+## Git reference revisions
+
+Remote branches were fetched with pruning and the checked-out default branches
+were fast-forwarded on 2026-08-12. The parent repository pins the exact commits
+through gitlinks; `.gitmodules` records the branch used for an intentional future
+`git submodule update --remote`. Inspect local state before advancing the parent
+gitlink pins; checked-out branches in this refresh used `git pull --ff-only`.
+
+| Reference | Canonical branch | Pinned commit |
+| --- | --- | --- |
+| `open-realm` | `main` | `550973e5172e13f8d0178cbeb69611d5af68935c` |
+| `whoa` | `master` | `ea1345636045635ac601b7d525eb0c38c6c0f6dd` |
+| `WoWee` | `master` | `8456c236b57140e98667d6d8188f5cd1cc226daf` |
+| `WowUnreal` | `main` | `c2a4b9827b2e7672e799085c5bf631d37c4ca5d3` |
+| `wow.export` | `main` | `c2fd7bde36a712be78a5da896c995b84fbfa2545` |
+| `blender-wow-studio/.../pywowlib` | `master` | `55276dc5c2195da7fe136638a2a59716622f8c65` |
+
+`blender-wow-studio-3.4-1.1.0_Experimental` and `noggit-red` are tracked
+snapshots, not top-level gitlinks. They do not have a local branch and require a
+separate, provenance-checked snapshot refresh instead of a blind pull. The
+embedded `pywowlib` gitlink is maintained independently as listed above.
+
 - `blender-wow-studio-3.4-1.1.0_Experimental/` - Blender add-on sources for M2/WMO import/export reference.
 - `wow.export/` - wow.export source tree and Blender OBJ importer reference.
 - `noggit-red/` - Noggit RED source tree from `https://gitlab.com/dirtbikercj/noggit-red`, used as a reference for WoW 3.3.5 map editing, ADT/WMO/M2 placement behavior, UID handling and editor workflows.

src/tools/verify_wmo_runtime_mesh_finalizer.gd.uid

@@ -0,0 +1 @@
+uid://bhj5k6lmi7na8

targets/04-renderer-fidelity.md

@@ -11,6 +11,11 @@
 Noggit используется как дополнительный ориентир композиции и authoring preview,
 но не заменяет оригинальный клиент как fidelity oracle.
 
+Benilla используется как pinned secondary reference для M2 animation/material
+architecture, particles/ribbons, WMO portal visibility и temporal test ideas. Его
+Vanilla 1.12.1/Bevy behavior не заменяет build-12340 captures и не подтверждает
+WotLK parity без отдельного fixture comparison.
+
 ## Reference corpus
 
 - [ ] Принять versioned CSV manifest и валидатор оригинальных captures.

targets/roadmap/02-rendering-and-graphics.md

@@ -15,6 +15,13 @@ Authoritative oracle — оригинальный клиент build 12340. Nogg
 обзорной композиции, placements и будущего Editor viewport, но не подтверждает
 точные lighting, shadow, liquid, material или effect semantics.
 
+Pinned Benilla source полезен как secondary implementation reference для
+pose/palette animation, global sequences, material/pass ordering, shared dynamic
+effect buffers, M2 particles/ribbons и WMO portal traversal. Поскольку Benilla
+ориентирован на Vanilla build 5875 и Bevy, каждое заимствованное правило сначала
+проверяется на build-12340 fixture и адаптируется к существующим Godot/M03
+ownership, scheduling и finalization boundaries.
+
 Reference corpus принимает versioned CSV и приватные captures. Для каждой
 выбранной локации базовый набор содержит две позиции: `wide` для sky/fog/WDL и
 общей композиции, `ground` для terrain/material/M2/WMO. Специализированные

targets/roadmap/05-ui-lua-audio.md

@@ -91,6 +91,12 @@
 - Original 3.3.5a FrameXML/Lua extracted from legally owned data is primary behavior corpus.
 - `rilua`/PUC-Rio are VM candidates/oracles, not complete WoW UI.
 - WowBench/Wowser/WowUnreal/WoWee provide API/event/loader test ideas.
+- Pinned [Benilla](https://github.com/samwhosung/benilla) provides a strong
+  engine-free TOC/FrameXML/Lua decomposition and compatibility-test reference:
+  document/load order, templates, anchors, widget identity, handler globals,
+  deterministic event/`OnUpdate` order, sandbox and SavedVariables. Its Vanilla
+  Lua 5.0 compatibility layer and missing secure/taint coverage are not WotLK
+  semantics and require a build-12340 corpus.
 
 ## Gate