крупное обновление документации
This commit is contained in:
@@ -0,0 +1,86 @@
|
||||
# FND — Foundation, Application and Data
|
||||
|
||||
## Цель
|
||||
|
||||
Создать стабильную платформу, на которой renderer, client runtime и Godot Editor могут развиваться независимо, используя одинаковые типы и build artifacts.
|
||||
|
||||
## FND-1. Project profiles и configuration
|
||||
|
||||
- Ввести `BuildProfile` и `CapabilitySet`.
|
||||
- Отделить user settings, developer settings, server connection profiles и content project settings.
|
||||
- Secrets хранить вне Git/Resource; поддержать environment/OS credential provider.
|
||||
- Настройки иметь schema version, defaults, validation, migration и reset-by-section.
|
||||
- `Blizzlike335` сделать неизменяемым базовым профилем; enhanced settings наследуют его явно.
|
||||
|
||||
## FND-2. Application lifecycle
|
||||
|
||||
- Реализовать state machine `Boot → DataCheck → Login → Realm → Character → Loading → InWorld → Disconnect/Recovery`.
|
||||
- Editor, sandbox и headless modes запускать разными composition roots.
|
||||
- Dependency injection выполнять composition layer; не использовать scene lookup как service locator.
|
||||
- Autoload ограничить действительно process-wide lifecycle services. Gameplay, renderer и editor sessions должны инстанцироваться и освобождаться явно.
|
||||
- Каждое состояние иметь cancellation, timeout, diagnostics и deterministic cleanup.
|
||||
|
||||
## FND-3. Domain primitives
|
||||
|
||||
- Typed IDs: content, server entry, entity, GUID, map, area, spell, item, quest, display и sound.
|
||||
- Typed coordinates и orientation; запретить `Vector3` как межслойный wire/domain contract.
|
||||
- Value objects для locale, money, duration, percentage, level, power type и flags.
|
||||
- Commands/events/read models не наследуют Node/Resource.
|
||||
- Serialization version и unknown-field policy определить до сохранения snapshots/replays.
|
||||
|
||||
## FND-4. Asset repository
|
||||
|
||||
- Описать archive chain/locale/patch precedence для 3.3.5a.
|
||||
- Отделить `original source → parsed canonical data → imported Godot resource → runtime cache`.
|
||||
- Ввести provenance: source archive/path/hash, parser version, import profile и dependency hashes.
|
||||
- Не изменять extracted upstream files; custom content подключать ordered overlays.
|
||||
- Dedup textures/materials/meshes по canonical key, а не по случайной Node lifetime.
|
||||
- Missing/corrupt asset policy: placeholder только в dev profile, structured error в fidelity runs.
|
||||
|
||||
## FND-5. Binary formats и typed tables
|
||||
|
||||
- MPQ: archive ordering, locale, listfile absence, encrypted/compressed entries.
|
||||
- BLP: paletted/DXT, alpha depths, mip chains, color space и wrap/filter metadata.
|
||||
- DBC: schema descriptors, localized strings, relationships, hot reload только в authoring mode.
|
||||
- WDT/WDL/ADT: tile existence, terrain, holes, layers, placements, liquids, distant data.
|
||||
- M2/SKIN/WMO: versioned structs, bounds, batches, materials, animation, attachments, portals.
|
||||
- Audio/interface assets: MP3/WAV, fonts, XML, Lua, TOC и SavedVariables formats.
|
||||
- Parser API возвращает typed result + diagnostics; partial parse не маскируется как success.
|
||||
- Differential tests сравнивают текущие parsers с независимыми implementations (`warcraft-rs`, `wow_dbc`, WowDBDefs-driven schemas) на одинаковых fixtures; reference disagreement регистрируется, а не выбирается по большинству.
|
||||
|
||||
## FND-6. Cache and build pipeline
|
||||
|
||||
- Единый content-addressed cache manifest для terrain/M2/WMO/characters/audio/navigation/UI.
|
||||
- Atomic staging → verify → publish; crash не оставляет валидно выглядящий partial artifact.
|
||||
- Cache version включает schema, parser, shader/material contract и profile.
|
||||
- Headless commands используют те же services, что Editor actions.
|
||||
- Добавить dependency graph и incremental rebuild по hash.
|
||||
- Папки generated/cache исключить из Git и при необходимости из Godot import через `.gdignore`.
|
||||
|
||||
## FND-7. Native boundary
|
||||
|
||||
- GDExtension использовать для binary parsing, compression/crypto, large buffer transforms и измеренных hot paths.
|
||||
- GDScript использовать для orchestration, Editor UI и presentation composition.
|
||||
- Перед добавлением Rust/C/C++ dependency фиксировать ABI boundary и ownership.
|
||||
- Через native boundary передавать packed arrays/immutable result objects, избегать вызова на каждый vertex/instance.
|
||||
- Версию Godot/GDExtension API закрепить; обновление проходит compatibility matrix.
|
||||
|
||||
## FND-8. Jobs and concurrency
|
||||
|
||||
- Общий `JobScheduler`: priority, bounded capacity, cancellation, progress, correlation ID.
|
||||
- Pure CPU work выполняется workers; scene tree и GPU resources финализируются main thread budget.
|
||||
- Один resource не модифицируется конкурентно; shared mutable collections защищаются.
|
||||
- Каждый submitted worker task дожидается completion/cleanup.
|
||||
- Session/world unload отменяет jobs и освобождает RIDs/resources детерминированно.
|
||||
|
||||
## Deliverables
|
||||
|
||||
- Foundation package без renderer/network dependencies.
|
||||
- Headless data probe и cache inspector.
|
||||
- Coordinate/parser/cache fixtures.
|
||||
- Architecture dependency checker.
|
||||
- Документированные memory/thread ownership rules.
|
||||
|
||||
## Gate
|
||||
|
||||
Одинаковые входы дают одинаковые manifests; application modes собираются разными roots; domain тестируется без SceneTree; cancellation и shutdown не оставляют jobs/RIDs.
|
||||
@@ -0,0 +1,102 @@
|
||||
# RND — Rendering and Graphics
|
||||
|
||||
## Цель
|
||||
|
||||
Воспроизвести визуальные правила WoW 3.3.5a и дать opt-in улучшения, сохранив frame pacing на больших мирах Godot.
|
||||
|
||||
## RND-1. Renderer architecture
|
||||
|
||||
- `WorldRenderFacade` принимает focus, environment snapshot и entity presentation commands.
|
||||
- `StreamingTargetPlanner` вычисляет desired state без Node creation.
|
||||
- `RenderBudgetScheduler` ограничивает main-thread finalize по типам операций.
|
||||
- Terrain, M2, WMO, liquid, sky, character, effects и debug overlays — отдельные services.
|
||||
- RenderingServer/RIDs применяются только там, где profiler доказал overhead scene tree.
|
||||
- Ownership каждого RID и cache entry документируется; world unload проверяет leaks.
|
||||
|
||||
## RND-2. World streaming
|
||||
|
||||
- WDT-driven tile catalog, priority по position/direction/velocity/camera frustum.
|
||||
- Prewarm, retain и hysteresis исключают churn на ADT boundaries.
|
||||
- Separate budgets для I/O, parse, mesh/material load, main-thread attach и eviction.
|
||||
- Cold/warm cache scenarios, teleport, rapid flight и camera rotation stress.
|
||||
- Cancellation stale jobs при teleport/map change.
|
||||
- Streaming focus не обязан быть Camera3D: player, spectator, editor viewport, capture tool.
|
||||
|
||||
## RND-3. Terrain
|
||||
|
||||
- Точная 145-vertex MCNK topology, holes, normals и coordinate seams.
|
||||
- Texture layer order, MCAL alpha variants, animation flags, repeat и mip behavior.
|
||||
- Control-splat/array implementation как Godot optimization с fidelity tests.
|
||||
- WDL/distant terrain и hierarchical LOD.
|
||||
- Terrain collision/query representation отдельно от visual mesh.
|
||||
- Editing path: sculpt, smooth, flatten, holes, texture paint, seam repair и rebake.
|
||||
|
||||
## RND-4. M2
|
||||
|
||||
- Static geometry, SKIN batches, blend modes, flags, UV transforms и texture lookup.
|
||||
- Native pivot-based skeletal animation, bone palettes, global sequences и animation lookup.
|
||||
- Billboards, attachments, key bones, events, cameras и bounding volumes.
|
||||
- Particles, ribbons, texture animation и material combiners.
|
||||
- Static doodads группировать spatial MultiMesh cells; animated/interactive entities не смешивать со static batching.
|
||||
- MultiMesh buffer updates выполнять батчем; cell size выбирать по culling, а не только draw-call minimum.
|
||||
|
||||
## RND-5. WMO
|
||||
|
||||
- Root/group materials, batches, vertex colors, multiple UV sets и doodad sets.
|
||||
- Portals/rooms, indoor/outdoor, BSP/collision, fog и group visibility.
|
||||
- MLIQ, skybox, lights и ambient color semantics.
|
||||
- Lightweight render cache для больших WMO и incremental group attach.
|
||||
- Editor tools для group/portal/doodad validation.
|
||||
|
||||
## RND-6. Characters and creatures
|
||||
|
||||
- Race/gender/customization from DBC.
|
||||
- Geosets, skin regions, hair/facial features и composited textures.
|
||||
- Equipment component models/textures, attachment points, sheath, enchant visuals.
|
||||
- Animation state resolver: locomotion, combat, casting, emotes, death, swim, mount, vehicle.
|
||||
- CreatureDisplayInfo/Extra/ModelData, NPC equipment, pets и shapeshift.
|
||||
- Character preview uses same presenter as world runtime.
|
||||
|
||||
## RND-7. Liquids
|
||||
|
||||
- MH2O/MCLQ layers, existence masks, heights, depth и liquid type.
|
||||
- Отдельные profiles water/ocean/magma/slime.
|
||||
- Blizzlike material: texture animation, alpha, lighting и fog behavior.
|
||||
- Enhanced material: normals, reflections, depth/shore blending — opt-in.
|
||||
- Liquid collision/swim state принадлежит gameplay/physics query, не shader.
|
||||
|
||||
## RND-8. Environment
|
||||
|
||||
- DBC-driven Light/LightParams/LightIntBand/LightFloatBand interpolation.
|
||||
- Server time, day/night, zone/subzone transitions.
|
||||
- Skyboxes, fog, ambient/directional light, weather visual state.
|
||||
- Blizzlike cheap shadow policy; enhanced selective character/object shadows отдельно.
|
||||
- Camera far plane, fog и streaming distances согласованы профилем.
|
||||
|
||||
## RND-9. Effects and presentation
|
||||
|
||||
- SpellVisual/SpellVisualKit-driven cast/impact/aura effects.
|
||||
- Projectiles, decals, dynamic objects, combat text и selection circles.
|
||||
- Weather particles и world emitters.
|
||||
- Cinematic/model cameras и loading transitions.
|
||||
- Effects have pooling, lifetime, visibility и per-frame budgets.
|
||||
|
||||
## RND-10. Graphical extensions
|
||||
|
||||
- Higher-resolution content overlays без модификации originals.
|
||||
- Anisotropy, extended draw distance, improved water/shadows, post-processing и upscaling.
|
||||
- Optional PBR approximation only when it does not replace Blizzlike material profile.
|
||||
- Graphics settings expose measurable cost and fallback.
|
||||
- Editor comparison viewport: Blizzlike/Enhanced side-by-side, screenshot и metric capture.
|
||||
|
||||
## Verification
|
||||
|
||||
- Paired checkpoints с original 3.3.5a по position/time/weather/camera.
|
||||
- Material/animation fixtures from independent references.
|
||||
- Perceptual diff плюс human approval для intentional deviations.
|
||||
- p50/p95/p99, max hitch, draw calls, visible objects, GPU/CPU memory и RID leak checks.
|
||||
- D3D12/Vulkan and quality profile matrix.
|
||||
|
||||
## Gate
|
||||
|
||||
Видимый мир не деградирует при декомпозиции; under-foot/near-field quality готова до появления в кадре; long traversal не создаёт recurring hitches/leaks; Enhanced всегда отключаем.
|
||||
@@ -0,0 +1,94 @@
|
||||
# NET — Network, Protocol and Session
|
||||
|
||||
## Цель
|
||||
|
||||
Реализовать точный клиентский протокол WoW 3.3.5a build 12340, изолировав транспорт и packet layout от gameplay/UI.
|
||||
|
||||
## NET-1. Transport
|
||||
|
||||
- Native TCP auth/world connections, DNS/IPv4/IPv6 policy и configurable endpoints.
|
||||
- Non-blocking read/write, bounded buffers, packet fragmentation/coalescing.
|
||||
- Cancellation, connect/read/write timeouts, keepalive и orderly shutdown.
|
||||
- Network thread работает с bytes; domain events применяются game thread.
|
||||
- Proxy mode только как explicit development adapter, не основной transport.
|
||||
|
||||
## NET-2. Authentication
|
||||
|
||||
- Logon challenge/proof SRP6 values и exact endian/normalization rules.
|
||||
- Realm list parsing, build/locale/platform fields и error mapping.
|
||||
- World auth digest, session key и header encryption state.
|
||||
- Credentials не логируются; session material очищается при disconnect.
|
||||
- Golden vectors и сравнение с TrinityCore/AzerothCore/Wowser/Whoa implementations.
|
||||
|
||||
## NET-3. Packet framework
|
||||
|
||||
- `PacketReader/Writer` с checked boundaries и explicit endianness.
|
||||
- Typed opcode registry generated/validated для build 12340.
|
||||
- Header framing, ARC4/drop policy, zlib compressed packets.
|
||||
- Packed GUID, bit masks, CString/fixed strings и localized text.
|
||||
- Unknown/unsupported opcode telemetry rate-limited; policy зависит от criticality.
|
||||
- Packet handlers возвращают domain events, не меняют scenes/UI.
|
||||
|
||||
## NET-4. Update fields and entity lifecycle
|
||||
|
||||
- Generated object/item/container/unit/player/gameobject/dynamicobject/corpse field descriptors.
|
||||
- `SMSG_UPDATE_OBJECT` blocks: values, movement, create, create2, out-of-range, near objects.
|
||||
- Partial mask application сохраняет неизвестные/необновлённые поля корректно.
|
||||
- Entity type/entry/display/faction/health/power/flags/ownership relationships.
|
||||
- Despawn/out-of-range/map transfer не оставляют presentation entities.
|
||||
|
||||
## NET-5. Movement synchronization
|
||||
|
||||
- Полный movement flags set, timestamps, position/orientation, pitch, fall/jump, spline elevation.
|
||||
- Start/stop/strafe/turn/pitch/jump/fall/land/swim/fly/heartbeat packets.
|
||||
- Transport GUID/seat/relative coordinates и server spline movement.
|
||||
- Client prediction history, acknowledgements и reconciliation metrics.
|
||||
- Teleport/worldport handshake и map transfer.
|
||||
- Anti-cheat-sensitive fields формируются строго по profile; client не симулирует authoritative NPC path.
|
||||
|
||||
## NET-6. Session domains
|
||||
|
||||
- Character enum/create/delete/rename/login/logout.
|
||||
- Time/account data/tutorial/action bars/initial spells.
|
||||
- Chat/channel/social/group/guild.
|
||||
- Combat/spells/auras/threat.
|
||||
- Items/inventory/loot/trade/vendor/mail/auction.
|
||||
- Quests/gossip/POI/taxi.
|
||||
- Instances/LFG/PvP/vehicles/calendar.
|
||||
- Каждый domain имеет отдельный handler module, fixtures и unsupported coverage report.
|
||||
|
||||
## NET-7. Reliability and diagnostics
|
||||
|
||||
- State-aware disconnect reason и recovery path.
|
||||
- Reconnect только когда protocol/server допускает; иначе безопасный возврат к login.
|
||||
- Packet trace modes: metadata-only default, redacted payload для tests, encrypted secrets never.
|
||||
- Correlation IDs session/request/entity.
|
||||
- Replay transport воспроизводит timing или deterministic step mode.
|
||||
- Network impairment harness: latency, jitter, loss, duplication, fragmentation и abrupt close.
|
||||
|
||||
## NET-8. Core compatibility
|
||||
|
||||
- Baseline protocol один, но server capabilities/quirks задаются adapter profile.
|
||||
- Не ветвить handlers по строке `if azerothcore` без documented capability.
|
||||
- Test matrix фиксирует core commit, DB revision, modules и config.
|
||||
- Custom opcodes располагаются в namespaced extension profile и не включены в Blizzlike335.
|
||||
|
||||
## NET-9. Warden compatibility
|
||||
|
||||
- Зафиксировать фактические требования Warden у supported TrinityCore/AzerothCore profiles.
|
||||
- Реализовывать только compatibility с тестовыми/private server environments и документированным build 12340 flow; OpenWC не предназначен для official/retail servers.
|
||||
- Module challenge/response, crypto/state и platform behavior изолировать в optional security adapter.
|
||||
- Любое исполнение загружаемого module code sandboxed, size/hash checked и отключаемо в development profile.
|
||||
- Добавить fixtures и failure UX для unsupported/invalid challenge; не использовать subsystem для обхода чужих защитных механизмов.
|
||||
|
||||
## Tools and references
|
||||
|
||||
- TrinityCore/AzerothCore source — authoritative server-side packet expectations.
|
||||
- Whoa — reverse-engineered client semantics.
|
||||
- Wowser — независимый auth/world proof-of-concept и test ideas.
|
||||
- WoWee/WowUnreal — coverage и lifecycle comparison.
|
||||
- Packet captures используются только легально, минимально и с redaction.
|
||||
|
||||
## Gate
|
||||
|
||||
Headless client проходит auth → realm → character → world; replay создаёт одинаковые domain events; malformed packets не читаются за границы; secrets отсутствуют в logs; обе core configurations проходят contract suite.
|
||||
@@ -0,0 +1,112 @@
|
||||
# GMP — Gameplay Systems
|
||||
|
||||
## Цель
|
||||
|
||||
Создать детерминированную клиентскую проекцию серверного gameplay и полный набор player intents WoW 3.3.5a без переноса authoritative правил на клиент.
|
||||
|
||||
## GMP-1. World model
|
||||
|
||||
- Typed entity registry и object hierarchy.
|
||||
- Components/read models: identity, transform, unit, player, item, gameobject, corpse, dynamic object.
|
||||
- Ownership, charm, pet, target, creator, transport и group relationships.
|
||||
- Reducers применяют domain events; presentation подписывается на changesets.
|
||||
- Snapshot/replay позволяют восстановить состояние без live socket.
|
||||
|
||||
## GMP-2. Input and movement
|
||||
|
||||
- Remappable action layer, keyboard/mouse и optional gamepad/accessibility mappings.
|
||||
- Walk/run/backpedal/strafe/turn/jump/fall/swim/fly/autorun.
|
||||
- Camera-relative или character-relative policy строго по original behavior.
|
||||
- Ground/collision query abstraction, slopes, water transition и falling.
|
||||
- Prediction/reconciliation только локального movement; corrections имеют smoothing/snap thresholds.
|
||||
- Debug flight/speed отделены от production profile.
|
||||
|
||||
## GMP-3. Selection and interaction
|
||||
|
||||
- Mouse/world picking, tab target, target/focus и target-of-target.
|
||||
- Hostility/faction/dead/visibility/selectability filters.
|
||||
- Facing, range, line-of-sight и interaction intents.
|
||||
- NPC flags определяют available services; client не выдумывает доступную функцию.
|
||||
- Gameobject use, gossip, trainer, vendor, mailbox, auctioneer, binder и flight master.
|
||||
|
||||
## GMP-4. Combat
|
||||
|
||||
- Auto attack/auto shot, swing state и attack stop.
|
||||
- Damage/heal/miss/absorb/resist/block/crit feedback.
|
||||
- Threat presentation, combat state, evade и unit flags.
|
||||
- Resources, regeneration presentation и combo points/runes where applicable.
|
||||
- Combat log canonical events отделены от floating text/UI formatting.
|
||||
- Server validates hit, damage и death; client показывает pending/cast state.
|
||||
|
||||
## GMP-5. Spells and auras
|
||||
|
||||
- Spellbook, ranks, passive/active, known/disabled spells.
|
||||
- Target requirements, range, facing, resource и client-predictable validation messages.
|
||||
- Cast/channel/interrupt/pushback, GCD и cooldowns.
|
||||
- Aura add/update/remove, stacks, duration, caster, dispel type и visibility.
|
||||
- Totems, shapeshift, pets, tracking, tradeskill casts.
|
||||
- Spell visual/audio descriptors separate from spell mechanics state.
|
||||
|
||||
## GMP-6. Death and recovery
|
||||
|
||||
- Death/release spirit, ghost, corpse, graveyard, reclaim delay.
|
||||
- Resurrection request/accept, spirit healer penalties.
|
||||
- Durability loss/repair и instance wipe/reset presentation.
|
||||
- Failure during map transfer/reconnect does not duplicate corpse/player state.
|
||||
|
||||
## GMP-7. Items and economy
|
||||
|
||||
- Inventory slots, bags, bank, keyring, equipment, ammo и currencies.
|
||||
- Stack/split/swap/equip/use/destroy with pending/server-confirmed states.
|
||||
- Loot windows, group rolls, master loot, disenchant и loot release.
|
||||
- Item fields, random properties, enchants, gems, durability, sets и cooldowns.
|
||||
- Vendor/buyback/repair, trade, mail, auction и guild bank.
|
||||
- Money formatting/display separated from authoritative transaction.
|
||||
|
||||
## GMP-8. Quests and progression
|
||||
|
||||
- Quest availability, accept, abandon, track, objectives, complete и reward choice.
|
||||
- Kill, item, gameobject, explore, spell, escort, timed, reputation objectives.
|
||||
- Chains, prerequisites, exclusive groups, repeatable/daily/weekly и conditions.
|
||||
- XP/rested/level, reputation, honor, achievements.
|
||||
- Skills, talents, glyphs, professions, recipes и trainers.
|
||||
- Quest state drives view models; authoring graph compiles to server-supported representation.
|
||||
|
||||
## GMP-9. World activities
|
||||
|
||||
- Area/subzone/exploration state и rest areas.
|
||||
- Taxi discovery/routes/flight, transports, elevators и boats.
|
||||
- Fishing, gathering, tracking, world events и scripted gameobjects.
|
||||
- Weather/time events feed render/audio but are owned by world state.
|
||||
- Minimap/world map POI and quest markers are projections, not quest logic.
|
||||
|
||||
## GMP-10. Social
|
||||
|
||||
- Chat types, channels, whispers, system messages и links.
|
||||
- Friends, ignore, who, AFK/DND.
|
||||
- Party/raid invites, leader, roles, loot rules, ready check, raid targets.
|
||||
- Guild roster, ranks, notes, MOTD, event/calendar.
|
||||
- Presence/reconnect updates and privacy/error handling.
|
||||
|
||||
## GMP-11. Instances, PvP and vehicles
|
||||
|
||||
- Difficulty, instance binds, lockouts, encounters, reset и transfer aborted.
|
||||
- LFG queue/proposal/roles/teleport/vote kick/rewards.
|
||||
- Duel, PvP flags, battleground queue/status/score/resurrection и arena teams.
|
||||
- Outdoor PvP objectives.
|
||||
- Vehicle seats, enter/exit/switch, possession action bar и transport-relative movement.
|
||||
|
||||
## GMP-12. Cinematics and scripted presentation
|
||||
|
||||
- Cinematic/movie start/stop, camera control и skippability.
|
||||
- Server-driven scripted sequences reflected as safe presentation commands.
|
||||
- Loading screens and map transitions preserve session state.
|
||||
- Gameplay input contexts prevent actions during restricted states.
|
||||
|
||||
## Testing order
|
||||
|
||||
Для каждой системы: reducer unit tests → packet/domain contract → offline scenario → live core integration → original-client comparison → latency/reconnect scenario.
|
||||
|
||||
## Gate
|
||||
|
||||
Gameplay state воспроизводим replay-ом; UI/render не владеют authoritative values; все intents имеют pending/confirmed/rejected lifecycle; core gameplay loop проходит end-to-end без оригинального клиента.
|
||||
@@ -0,0 +1,97 @@
|
||||
# UIA — UI, Lua, Addons and Audio
|
||||
|
||||
## Цель
|
||||
|
||||
Воспроизвести UI/addon semantics клиента 3.3.5a, сохранив возможность modern UI overlays и полноценную audio presentation.
|
||||
|
||||
## UIA-1. UI architecture
|
||||
|
||||
- Screen flow отделён от in-world HUD.
|
||||
- UI читает immutable view models и отправляет intents.
|
||||
- Godot Control tree является presentation backend, а не gameplay model.
|
||||
- Input contexts: login, character, world, chat, modal, targeting, vehicle, cinematic.
|
||||
- Scale, safe area, resolution, font и localization учитываются на уровне layout system.
|
||||
|
||||
## UIA-2. Frontend screens
|
||||
|
||||
- Data/license check, login, realm list и connection errors.
|
||||
- Character selection/create/delete/rename.
|
||||
- Race/class/customization previews тем же character renderer.
|
||||
- Loading screens по map/instance, progress и cancellation policy.
|
||||
- Disconnect/reconnect dialogs и account/server notices.
|
||||
|
||||
## UIA-3. FrameXML
|
||||
|
||||
- TOC parser: metadata, dependencies, optional deps, SavedVariables и load order.
|
||||
- XML includes, templates, `virtual`, inheritance и named/anonymous objects.
|
||||
- Frames, Regions, Textures, FontStrings, Layers и Scripts.
|
||||
- Anchors, dimensions, strata, frame level, draw layers, clipping и scale.
|
||||
- Widget types: Button, CheckButton, EditBox, Slider, StatusBar, ScrollFrame, MessageFrame, Tooltip, Cooldown, Model и Minimap.
|
||||
- Handler scripts: OnLoad, OnEvent, OnUpdate, mouse/keyboard/drag/show/hide/value events.
|
||||
|
||||
## UIA-4. Lua runtime
|
||||
|
||||
- Внутренний `LuaRuntime` позволяет сравнить/заменить PUC-Rio 5.1.1 и `rilua`.
|
||||
- Restricted libraries, byte strings, number semantics, globals, `bit` и error formatting.
|
||||
- VM lifetime: one UI environment per client session/profile with controlled reset.
|
||||
- Incremental GC имеет frame budget и metrics.
|
||||
- Native functions возвращают stable Lua values, а не Godot/Rust/C++ objects напрямую.
|
||||
- VM backend выбирается ADR после official + WoW-specific corpus.
|
||||
|
||||
## UIA-5. WoW API and event system
|
||||
|
||||
- API inventory строится из 3.3.5a FrameXML/Lua usage и независимых references.
|
||||
- Реализация группируется: unit, spell, aura, item, quest, group, chat, map, CVar, bindings, frames.
|
||||
- Event dispatcher имеет deterministic ordering, argument contracts и registration lifecycle.
|
||||
- `OnUpdate` throttling не меняет original semantics в Blizzlike335.
|
||||
- API, требующий server state, читает gameplay read model или создаёт intent; raw packets недоступны.
|
||||
- Missing API выдаёт диагностируемую ошибку/coverage report, а не silent nil where incompatible.
|
||||
|
||||
## UIA-6. Security, taint and addons
|
||||
|
||||
- Secure/insecure execution origins.
|
||||
- Protected functions/actions, secure templates и combat lockdown.
|
||||
- Taint propagation through variables/tables/functions в пределах подтверждённой 3.3.5a модели.
|
||||
- Addon memory/CPU/error isolation и configurable script limits без скрытого изменения default behavior.
|
||||
- SavedVariables account/character scopes, serialization, corruption recovery и atomic writes.
|
||||
- Addon compatibility tiers: loads, renders, functional, secure-combat verified.
|
||||
- Headless addon runner и UI inspector входят в AuthoringStudio/Test Center.
|
||||
|
||||
## UIA-7. Default UI coverage
|
||||
|
||||
- Unit/player/target/focus/party/raid frames.
|
||||
- Action bars, stance/pet/vehicle bars, cooldowns и keybindings.
|
||||
- Buffs/debuffs, cast bars, combat text и errors.
|
||||
- Bags, character, spellbook, talents, glyphs, skills, professions.
|
||||
- Quest log/tracker/gossip, map/minimap/taxi.
|
||||
- Chat, social, guild, calendar, LFG, PvP score.
|
||||
- Vendor, trainer, bank, mail, auction, trade, loot и roll.
|
||||
- Game menu, settings, macros, addons и help.
|
||||
|
||||
## UIA-8. Audio
|
||||
|
||||
- Typed DBC wrappers for SoundEntries, ZoneMusic, IntroMusic, Ambience and related tables.
|
||||
- Decoder/streaming/cache for MP3/WAV with category budgets.
|
||||
- Music day/night/zone transitions and crossfade.
|
||||
- Ambient loops, random emitters, indoor/outdoor и weather.
|
||||
- Positional world sounds, footsteps, water, spells, combat, NPC voice и UI feedback.
|
||||
- Audio events come from presentation descriptors; UI/gameplay do not manipulate players directly.
|
||||
- Device change, focus/mute policy, category volumes и missing sound diagnostics.
|
||||
|
||||
## UIA-9. Localization and accessibility
|
||||
|
||||
- Locale-aware fonts, fallback, text encoding и layout expansion.
|
||||
- Keybindings fully remappable; mouse sensitivity/inversion and optional gamepad.
|
||||
- UI scale, contrast/color-blind profiles, subtitle/text alternatives where possible.
|
||||
- Critical state does not rely only on color/audio.
|
||||
- Enhanced accessibility remains compatible with server and can coexist with Blizzlike visuals.
|
||||
|
||||
## References
|
||||
|
||||
- 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.
|
||||
|
||||
## Gate
|
||||
|
||||
Default UI boots deterministically; selected real addons pass declared tiers; secure actions fail correctly during combat; Lua GC/OnUpdate remain within budgets; UI is replaceable without changing gameplay/network.
|
||||
@@ -0,0 +1,109 @@
|
||||
# EDT — Godot Editor and Content Authoring
|
||||
|
||||
## Цель
|
||||
|
||||
Превратить Godot Editor в единую среду расширения мира, gameplay, UI, audio и graphics с безопасным build/deploy/playtest workflow.
|
||||
|
||||
## EDT-1. Plugin platform
|
||||
|
||||
- `addons/openwc_editor` регистрирует workspace, docks, inspector/import/gizmo/debugger plugins.
|
||||
- `_enter_tree/_exit_tree` симметричны: все controls/plugins/signals/jobs снимаются без leaks.
|
||||
- UI вызывает authoring application services; не пишет SQL/files/scene tree напрямую.
|
||||
- Editor selection отделена от runtime preview nodes.
|
||||
- Shared services получают context через dependency injection, не global editor singleton.
|
||||
|
||||
## EDT-2. Workspace and UX
|
||||
|
||||
- World viewport, Content Browser, Outliner, Inspector, Validation, History, Build, Database, Test Center.
|
||||
- Search/filter/favorites/recent items и stable links между сущностями.
|
||||
- Multi-selection и bulk edits показывают scope/diff.
|
||||
- Diagnostics имеют severity/code/location/fix; double-click открывает field/node/world position.
|
||||
- Layout/workspace preferences сохраняются отдельно от Content Project.
|
||||
|
||||
## EDT-3. Commands, undo and recovery
|
||||
|
||||
- Любая mutation — command с execute/undo/description/affected IDs.
|
||||
- Terrain strokes агрегируются в bounded deltas; большие операции используют snapshots/chunks.
|
||||
- Autosave recovery journal атомарный и имеет schema version.
|
||||
- External changes обнаруживаются через hashes; merge/overwrite требует решения пользователя.
|
||||
- Quick Fix всегда previewable и undoable.
|
||||
|
||||
## EDT-4. Import and asset browser
|
||||
|
||||
- MPQ/archive browser, locale/patch source provenance и extraction jobs.
|
||||
- Preview BLP, DBC rows, M2 animations/materials, WMO groups/portals, ADT layers и audio.
|
||||
- Godot import plugins применяются только к authoring source formats, где lifecycle `.import` полезен.
|
||||
- Raw extracted corpus не должен вызывать неконтролируемый массовый Godot reimport.
|
||||
- Batch conversion использует staging, cancellation, cache hash и report.
|
||||
|
||||
## EDT-5. World editing
|
||||
|
||||
- Map/tile/chunk navigation и coordinate overlays.
|
||||
- Terrain sculpt/smooth/flatten/noise/stamps/holes.
|
||||
- Texture layers, alpha painting, shading и liquids.
|
||||
- M2/WMO placement, snapping, transforms, doodad sets и unique ID allocation.
|
||||
- Creature/gameobject spawns, groups, formations, patrol/escort paths.
|
||||
- Areas, triggers, graveyards, teleports, taxi/transport points, sound/weather volumes.
|
||||
- Collision/navmesh/streaming/render-cost visualization.
|
||||
|
||||
## EDT-6. Data editors
|
||||
|
||||
- Creature/gameobject templates, models, equipment, movement and text.
|
||||
- Item/loot/vendor/trainer/profession editors.
|
||||
- Quest form + dependency/progression graph + localization.
|
||||
- Gossip/conditions/SmartAI graph with raw representation inspector.
|
||||
- Spawn/pool/game event/phase editor.
|
||||
- Dungeon package, encounter state graph, doors/triggers/lockouts/loot.
|
||||
- UI/addon manifest, CVar/keybinding и audio zone configuration.
|
||||
|
||||
## EDT-7. Navigation
|
||||
|
||||
- `recast-rs` optional offline backend behind navigation build interface.
|
||||
- Bake profiles: agent size/climb/slope/cell/region/tile parameters.
|
||||
- Walkability, disconnected islands, path cost, off-mesh links и dynamic door states.
|
||||
- Quest giver/objective/turn-in reachability; patrol/escort validation.
|
||||
- OpenWC cache отделён от server mmap until compatibility proven.
|
||||
|
||||
## EDT-8. Graphics extension tools
|
||||
|
||||
- Material/shader profile editor с Blizzlike/Enhanced comparison.
|
||||
- Texture replacement/upscale overlays и mip/alpha/color-space validation.
|
||||
- Water/sky/weather/light preview with fixed time and reference capture.
|
||||
- Character/equipment/animation/attachment preview.
|
||||
- Spell visual/particle/ribbon authoring where formats permit.
|
||||
- Quality preset cost preview и automatic render checkpoint generation.
|
||||
|
||||
## EDT-9. Content Project
|
||||
|
||||
- Git-friendly files, schema version, symbolic IDs, dependencies и capability requirements.
|
||||
- Original data referenced, never copied silently.
|
||||
- Overlay priority/conflict report и semantic merges.
|
||||
- Deterministic numeric ID allocation per server profile.
|
||||
- Localization bundles, scripts, client assets, tests и package manifests.
|
||||
- Schema migrations with backup, fixture and loss policy.
|
||||
|
||||
## EDT-10. Build, deploy and playtest
|
||||
|
||||
```text
|
||||
Validate → Compile → Bake → Diff → Package → Dry-run
|
||||
→ Apply dev DB/module/assets → Start/reload core → Launch client at context
|
||||
→ Collect logs/results → Roll back disposable environment
|
||||
```
|
||||
|
||||
- Jobs cancellable, progress-aware and identical to headless CI services.
|
||||
- Production target physically/logically separated and disabled by default.
|
||||
- Server reload used only for tables known to support it; otherwise restart.
|
||||
- Playtest bundle records content/core/client revisions and profile.
|
||||
- One-click convenience never hides SQL/module/client artifact diff.
|
||||
|
||||
## EDT-11. Extensibility
|
||||
|
||||
- `ContentTypeDescriptor`: schema, icon, inspector, validator, compiler, presenter.
|
||||
- `EditorTool`: selection contract, command factory, gizmo/overlay.
|
||||
- `BuildStep`: inputs/outputs/cache key/cancellation/diagnostics.
|
||||
- Plugin declares API version, dependencies, permissions and migrations.
|
||||
- User plugins cannot mutate production DB or original assets outside approved services.
|
||||
|
||||
## Best-practice gate
|
||||
|
||||
Plugin reload clean; undo/save/reload deterministic; long jobs do not block Editor; preview nodes disposable; every deployment reproducible headless; common scenarios require no manual SQL.
|
||||
@@ -0,0 +1,84 @@
|
||||
# SRV — TrinityCore and AzerothCore Integration
|
||||
|
||||
## Цель
|
||||
|
||||
Поддержать server emulators как versioned backends: protocol-compatible runtime, безопасное редактирование данных и расширение mechanics через modules/scripts.
|
||||
|
||||
## SRV-1. Environment model
|
||||
|
||||
- `ServerEnvironment`: family, core commit, DB revision, modules, config profile, endpoints и data artifact versions.
|
||||
- Отдельные disposable, local-dev, shared-test, staging и production classes.
|
||||
- Credentials/secrets вне Content Project.
|
||||
- Capability discovery проверяет schema fingerprint и optional modules/tables/hooks.
|
||||
- Unknown environment всегда read-only.
|
||||
|
||||
## SRV-2. Database snapshots
|
||||
|
||||
- Read-only import world schema subsets с provenance/checksum.
|
||||
- Auth/characters DB открываются только для нужных test/admin сценариев и никогда не становятся content source.
|
||||
- Snapshot filters reproducible; personal/account data excluded.
|
||||
- Canonical entities preserve supported fields and explicitly record unsupported/raw extras.
|
||||
- Incremental snapshot возможен, но full consistency snapshot остаётся verification path.
|
||||
|
||||
## SRV-3. Canonical mappings
|
||||
|
||||
- Creature/gameobject templates, models, spawns, addons, formations, movement, texts.
|
||||
- Quests, relations, objectives, POI, conditions, gossip.
|
||||
- Loot/reference loot, vendors, trainers, items, reputation.
|
||||
- SmartAI, script names, waypoint/script tables.
|
||||
- Instances, encounters, LFG, graveyards, teleports, game events, weather, transports.
|
||||
- Каждая mapping имеет per-core capability table и round-trip tests.
|
||||
|
||||
## SRV-4. Change sets and SQL
|
||||
|
||||
- Immutable change set: target fingerprint, preconditions, ordered operations, checksum.
|
||||
- SQL generation соответствует conventions целевого core/profile.
|
||||
- Custom SQL хранится в version control и compatible custom/module directory, не только применяется напрямую.
|
||||
- Dry-run на disposable DB, targeted post-apply queries, core startup smoke.
|
||||
- Idempotent migration или безопасное precondition failure.
|
||||
- Rollback где возможен; destructive/irreversible operations требуют backup и явного подтверждения.
|
||||
|
||||
## SRV-5. Scripts and modules
|
||||
|
||||
- DB/SmartAI для выразимых data-driven mechanics.
|
||||
- C++ module/script skeleton для mechanics, требующих server hooks.
|
||||
- AzerothCore modules namespaced config/SQL/hooks; core patch — только если hook принципиально отсутствует.
|
||||
- TrinityCore adapter следует его текущим script/customization conventions отдельно.
|
||||
- Build artifact включает source, config.dist, SQL, tests и compatibility manifest.
|
||||
- Client extension capability договаривается явно; hidden custom opcode запрещён.
|
||||
|
||||
## SRV-6. Server data artifacts
|
||||
|
||||
- DBC/maps/vmaps/mmaps versions связываются с ContentBundleManifest.
|
||||
- Custom map требует согласованного client terrain, server maps/collision/pathfinding и DB Map/Area data.
|
||||
- OpenWC navmesh не объявляется mmap до binary/query/live behavior compatibility.
|
||||
- Asset/map IDs распределяются стабильно и проверяются на collision.
|
||||
- Client/server package mismatch блокирует playtest с actionable diagnostic.
|
||||
|
||||
## SRV-7. Protocol compatibility
|
||||
|
||||
- Baseline 3.3.5a build 12340 остаётся общим.
|
||||
- Core-specific quirks описываются named capabilities и fixtures.
|
||||
- Custom extensions используют versioned handshake/profile и fallback/rejection.
|
||||
- Server authority одинаково соблюдается для обеих families.
|
||||
- Compatibility matrix закрепляет tested commits, а не расплывчатое «поддерживает AzerothCore».
|
||||
|
||||
## SRV-8. Test environments
|
||||
|
||||
- Docker/managed local environment для repeatable DB/core setup, где поддерживается.
|
||||
- Seed accounts/characters synthetic и не содержат реальные credentials.
|
||||
- Reset DB через assembler/base + project migrations.
|
||||
- Logs world/auth/database/client собираются с correlation metadata.
|
||||
- DB-only change test, module build test, startup smoke, scripted client scenario и cleanup.
|
||||
|
||||
## SRV-9. Existing tools
|
||||
|
||||
- Keira3 — reference для field semantics, SQL generation и AzerothCore DB UX.
|
||||
- AzerothCore wiki/schema/module template — primary backend documentation.
|
||||
- TrinityCore source/schema/tools — primary для Trinity profile.
|
||||
- Noggit/WoW modding tools — client-world authoring reference, но не server schema oracle.
|
||||
- OpenWC Editor объединяет workflow, но сохраняет raw SQL preview и ссылки на upstream docs.
|
||||
|
||||
## Gate
|
||||
|
||||
Одна canonical сущность проходит import → edit → diff → dry-run → apply → reimport на каждом supported profile без silent loss; module/content packages воспроизводимы; production write disabled by default; test environment очищается.
|
||||
@@ -0,0 +1,113 @@
|
||||
# QAR — Fidelity, Quality, CI and Release
|
||||
|
||||
## Цель
|
||||
|
||||
Сделать точность, производительность и расширяемость проверяемыми свойствами, а не обещаниями.
|
||||
|
||||
## QAR-1. Fidelity lab
|
||||
|
||||
- Каталог сценариев original client 3.3.5a: setup, input, server state, expected output.
|
||||
- Paired screenshots/video/log/packet/state evidence с provenance.
|
||||
- Поведение классифицируется: `Unknown`, `Observed`, `Matched`, `Intentional deviation`, `Blocked`.
|
||||
- Independent references могут подсказать hypothesis, но не повышают статус без evidence.
|
||||
- Blizzlike bugs/exploits обрабатываются policy decision: protocol compatibility отдельно от harmful behavior.
|
||||
|
||||
## QAR-2. Test layers
|
||||
|
||||
- Native unit tests: parsers, crypto, compression, coordinates, math, caches.
|
||||
- GDScript/domain unit tests: reducers, validators, commands, view models.
|
||||
- Contract tests: packets, DB adapters, Lua API, content schemas, renderer facade.
|
||||
- Scene tests: lifecycle, input, UI, renderer attachment, EditorPlugin reload.
|
||||
- Integration: disposable core/DB, import/build/deploy, login/world/gameplay.
|
||||
- E2E: leveling loop, dungeon, PvP/service flows и authoring vertical slices.
|
||||
- Visual/performance and exploratory design tests complement automation.
|
||||
|
||||
## QAR-3. Godot testing stack
|
||||
|
||||
- Оценить GdUnit4 как candidate для Godot 4.6 GDScript/scene/CI tests.
|
||||
- Native GDExtension tests используют подходящий C++ test runner отдельно от engine-internal doctest unless Godot itself is rebuilt.
|
||||
- Headless commands возвращают non-zero и machine-readable JUnit/JSON reports.
|
||||
- Scene tests не зависят от proprietary assets: synthetic fixtures or locally resolved optional corpus.
|
||||
- Flaky retries не превращают failure в success; instability измеряется и исправляется.
|
||||
|
||||
## QAR-4. Golden and property testing
|
||||
|
||||
- Golden binary structures and exact-byte packet vectors.
|
||||
- Parser round-trip where format permits; malformed/truncated/fuzz corpus.
|
||||
- Coordinate transform property tests and known world points.
|
||||
- Deterministic content manifests, SQL diff and migration before/after fixtures.
|
||||
- Lua oracle corpus, navmesh reference counts/queries, material descriptor mappings.
|
||||
|
||||
## QAR-5. Performance budgets
|
||||
|
||||
- Startup/data check/login/world entry.
|
||||
- Streaming cold/warm traversal and teleport.
|
||||
- CPU/GPU frame p50/p95/p99/max hitch, draw calls, memory и descriptors.
|
||||
- Network decode/apply queues and reconciliation error.
|
||||
- UI `OnUpdate`, event fan-out, Lua allocations/GC.
|
||||
- Editor import/bake/validation latency and cancellation responsiveness.
|
||||
- Server deployment/playtest turnaround.
|
||||
- Budgets hardware/profile-specific and trend tracked.
|
||||
|
||||
## QAR-6. Observability
|
||||
|
||||
- Structured logging categories and stable diagnostic codes.
|
||||
- Correlation IDs session/job/entity/content change set.
|
||||
- Runtime metrics: queues, entities, cache hit, resource counts, RIDs, packet rate.
|
||||
- Editor metrics: jobs, diagnostics, artifact hashes, DB operations.
|
||||
- Debug overlays and Godot profiler/visual profiler capture workflow.
|
||||
- Payload, credentials, chat/personal content redacted by default.
|
||||
|
||||
## QAR-7. CI pipeline
|
||||
|
||||
Pull request gates:
|
||||
|
||||
1. formatting/static analysis/document links/target marker validation;
|
||||
2. native build and unit tests;
|
||||
3. headless Godot load and GDScript tests;
|
||||
4. affected parser/protocol/content/adapter contracts;
|
||||
5. deterministic artifact check;
|
||||
6. renderer smoke if visual code changed;
|
||||
7. license/dependency audit.
|
||||
|
||||
Nightly/weekly:
|
||||
|
||||
- disposable TrinityCore/AzerothCore integration;
|
||||
- full packet/Lua/parser replay corpus;
|
||||
- visual checkpoints on available GPU runners;
|
||||
- long traversal, reconnect, cache migration and soak;
|
||||
- previous schema/Godot/core compatibility matrix.
|
||||
|
||||
## QAR-8. Security and robustness
|
||||
|
||||
- Bounds checked binary parsing and fuzzing.
|
||||
- Lua sandbox/taint/protected actions.
|
||||
- DB least privilege, read-only default, production protection.
|
||||
- Untrusted addon/content/plugin permission model.
|
||||
- Dependency license/advisory/source pin audit.
|
||||
- Atomic files, backup, recovery and rollback.
|
||||
- No proprietary assets, secrets or production dumps in repository/artifacts.
|
||||
|
||||
## QAR-9. Documentation and decisions
|
||||
|
||||
- Architecture/API/schema changes update docs and ADR в том же work package.
|
||||
- Каждый самостоятельный module имеет specification по `docs/DOCUMENTATION_STANDARD.md`: purpose, boundaries, public API, inputs/outputs, data flow, ownership, errors, tests и source map.
|
||||
- Data-flow diagram обязательна всегда; state/sequence/dependency diagrams обязательны по сложности/lifecycle rules стандарта.
|
||||
- Inline docs являются источником точной сигнатуры, module spec — источником концепции и фактического статуса.
|
||||
- Tooling candidates tracked in `docs/TOOLING_CATALOG.md` with status and pinned version.
|
||||
- Feature coverage links implementation, tests, fidelity evidence and known gaps.
|
||||
- Generated API docs for documented GDScript/GDExtension public surface включаются в quality gate, когда pipeline подготовлен.
|
||||
- Contributor workflow describes smallest reproducible diagnostic commands.
|
||||
|
||||
## QAR-10. Packaging and release
|
||||
|
||||
- Client ships without Blizzard data and guides user to select legally owned install.
|
||||
- Import/cache first-run is resumable and reports disk/time requirements.
|
||||
- Platform packages include matching GDExtension libraries and dependency notices.
|
||||
- Content package and server module releases version independently with compatibility manifest.
|
||||
- Save/settings/content schema migrations tested from supported previous versions.
|
||||
- Release channels: developer, preview, stable; fidelity gaps visible in notes.
|
||||
|
||||
## Exit gate
|
||||
|
||||
Release candidate passes required core/platform/profile matrix; no critical unowned diagnostic; performance regression within approved bounds; artifacts reproducible and license-clean; known fidelity deviations documented.
|
||||
Reference in New Issue
Block a user