крупное обновление документации
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.
|
||||
Reference in New Issue
Block a user