diff --git a/.gitmodules b/.gitmodules index d789922..c661e6b 100644 --- a/.gitmodules +++ b/.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 diff --git a/RENDER.md b/RENDER.md index 969e0c8..7b6d2e8 100644 --- a/RENDER.md +++ b/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; diff --git a/addons/mpq_extractor/bin/~libmpq_extractor.windows.x86_64.dll~RF2384413f.TMP b/addons/mpq_extractor/bin/~libmpq_extractor.windows.x86_64.dll~RF2384413f.TMP new file mode 100644 index 0000000..ffb72d5 Binary files /dev/null and b/addons/mpq_extractor/bin/~libmpq_extractor.windows.x86_64.dll~RF2384413f.TMP differ diff --git a/addons/mpq_extractor/bin/~libmpq_extractor.windows.x86_64.dll~RF23fd4143.TMP b/addons/mpq_extractor/bin/~libmpq_extractor.windows.x86_64.dll~RF23fd4143.TMP new file mode 100644 index 0000000..ffb72d5 Binary files /dev/null and b/addons/mpq_extractor/bin/~libmpq_extractor.windows.x86_64.dll~RF23fd4143.TMP differ diff --git a/docs/REFERENCES.md b/docs/REFERENCES.md index fe8bf90..16f29af 100644 --- a/docs/REFERENCES.md +++ b/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. diff --git a/docs/TOOLING_CATALOG.md b/docs/TOOLING_CATALOG.md index 13d0bb5..547d9ac 100644 --- a/docs/TOOLING_CATALOG.md +++ b/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. diff --git a/reference/README.md b/reference/README.md index f9f5eba..35d19b0 100644 --- a/reference/README.md +++ b/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. diff --git a/reference/WoWee b/reference/WoWee index 626243e..8456c23 160000 --- a/reference/WoWee +++ b/reference/WoWee @@ -1 +1 @@ -Subproject commit 626243e937fb93965fa583a6507ed5a1aa7dda4b +Subproject commit 8456c236b57140e98667d6d8188f5cd1cc226daf diff --git a/reference/blender-wow-studio-3.4-1.1.0_Experimental/io_scene_wmo/pywowlib b/reference/blender-wow-studio-3.4-1.1.0_Experimental/io_scene_wmo/pywowlib index 72857a8..55276dc 160000 --- a/reference/blender-wow-studio-3.4-1.1.0_Experimental/io_scene_wmo/pywowlib +++ b/reference/blender-wow-studio-3.4-1.1.0_Experimental/io_scene_wmo/pywowlib @@ -1 +1 @@ -Subproject commit 72857a882b823fd375c2239479983e51043c6a3e +Subproject commit 55276dc5c2195da7fe136638a2a59716622f8c65 diff --git a/reference/open-realm b/reference/open-realm index c7ed054..550973e 160000 --- a/reference/open-realm +++ b/reference/open-realm @@ -1 +1 @@ -Subproject commit c7ed0545c8c6050f111c1127febca9072f083583 +Subproject commit 550973e5172e13f8d0178cbeb69611d5af68935c diff --git a/reference/whoa b/reference/whoa index 74bc963..ea13456 160000 --- a/reference/whoa +++ b/reference/whoa @@ -1 +1 @@ -Subproject commit 74bc963a1c3c586a8960e6be937ca5713746bf77 +Subproject commit ea1345636045635ac601b7d525eb0c38c6c0f6dd diff --git a/reference/wow.export b/reference/wow.export index 7f8d4f8..c2fd7bd 160000 --- a/reference/wow.export +++ b/reference/wow.export @@ -1 +1 @@ -Subproject commit 7f8d4f8784696980101fb641dfca772af0d8d689 +Subproject commit c2fd7bde36a712be78a5da896c995b84fbfa2545 diff --git a/src/tools/verify_wmo_runtime_mesh_finalizer.gd.uid b/src/tools/verify_wmo_runtime_mesh_finalizer.gd.uid new file mode 100644 index 0000000..9ad8097 --- /dev/null +++ b/src/tools/verify_wmo_runtime_mesh_finalizer.gd.uid @@ -0,0 +1 @@ +uid://bhj5k6lmi7na8 diff --git a/targets/04-renderer-fidelity.md b/targets/04-renderer-fidelity.md index b6622ac..d629e99 100644 --- a/targets/04-renderer-fidelity.md +++ b/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. diff --git a/targets/roadmap/02-rendering-and-graphics.md b/targets/roadmap/02-rendering-and-graphics.md index fc9a73f..07cb751 100644 --- a/targets/roadmap/02-rendering-and-graphics.md +++ b/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. Специализированные diff --git a/targets/roadmap/05-ui-lua-audio.md b/targets/roadmap/05-ui-lua-audio.md index 2cb9559..52f4757 100644 --- a/targets/roadmap/05-ui-lua-audio.md +++ b/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