136 lines
7.1 KiB
Markdown
136 lines
7.1 KiB
Markdown
# Контент, клиентские данные и серверная БД
|
||
|
||
## Источник истины
|
||
|
||
Пользовательские изменения хранятся в Content Project. Original client data и server DB являются импортируемыми upstream-источниками; generated cache, SQL и packages являются build artifacts.
|
||
|
||
```text
|
||
upstream snapshot + user content + build profile → validated artifacts
|
||
```
|
||
|
||
## Структура Content Project
|
||
|
||
```text
|
||
content/projects/<project>/
|
||
project.json
|
||
manifests/
|
||
maps/
|
||
placements/
|
||
creatures/
|
||
gameobjects/
|
||
quests/
|
||
dialogues/
|
||
loot/
|
||
encounters/
|
||
dungeons/
|
||
localization/
|
||
scripts/
|
||
client_assets/
|
||
tests/
|
||
```
|
||
|
||
Файлы должны быть детерминированными, Git-friendly, с явными `schema_version`, stable symbolic ID и минимальным шумом форматирования. Generated IDs хранятся в allocation manifest, чтобы две сборки давали одинаковый результат.
|
||
|
||
## Идентификаторы и ссылки
|
||
|
||
- Authoring использует symbolic ID вида `quest.my_pack.bandit_problem`.
|
||
- Server numeric entry выделяется allocator-ом по профилю окружения.
|
||
- WoW GUID не используется как content ID.
|
||
- Ссылки типизированы и проверяются до сборки.
|
||
- Удаление сущности с входящими ссылками требует явного cascade/replacement решения.
|
||
|
||
## Координаты
|
||
|
||
Определяются отдельные типы `CanonicalWowPosition`, `GodotWorldPosition`, `AdtTileCoordinate`, `AdtChunkCoordinate`, `LocalTilePosition`, orientation и transport-relative position.
|
||
|
||
Только `CoordinateMapper` выполняет преобразования. Axis swap, origin, handedness, rotation units и scale фиксируются тестовыми golden points. Ручные преобразования в renderer, SQL exporter или gizmo запрещены.
|
||
|
||
## Server snapshot
|
||
|
||
Read-only import создаёт versioned snapshot с provenance:
|
||
|
||
- core family и commit/revision;
|
||
- world/auth/characters schema version;
|
||
- время получения;
|
||
- набор импортированных таблиц;
|
||
- checksum и applied filters.
|
||
|
||
Snapshot нужен для поиска, ссылок, offline validation и diff. Credentials и персональные данные в snapshot не включаются.
|
||
|
||
## Каноническая модель и adapters
|
||
|
||
Редактор работает с `QuestDefinition`, `CreatureTemplate`, `CreatureSpawn`, `GameObjectDefinition`, `LootTable`, `Dialogue`, `Condition`, `EncounterDefinition`. Адаптеры `TrinityCore335` и `AzerothCore335` отвечают за конкретные таблицы, flags, SmartAI/script conventions и capabilities.
|
||
|
||
Нельзя считать близкие схемы идентичными. Перед записью adapter проверяет fingerprint схемы. Unsupported property выдаёт ошибку или documented degradation, но не игнорируется молча.
|
||
|
||
## Change set
|
||
|
||
Build генерирует immutable change set:
|
||
|
||
- metadata и target profile;
|
||
- preconditions;
|
||
- ordered operations;
|
||
- SQL preview;
|
||
- affected entities/tables;
|
||
- validation report;
|
||
- rollback или описание необратимости;
|
||
- checksum.
|
||
|
||
Apply сначала выполняет dry-run на disposable/dev DB. Повторное применение должно быть idempotent либо безопасно отклоняться precondition-ом.
|
||
|
||
## Клиентские данные
|
||
|
||
Custom locations и mechanics могут требовать согласованных изменений:
|
||
|
||
- ADT/WDT/WDL, M2/WMO/BLP;
|
||
- DBC overlays;
|
||
- minimap/world map assets;
|
||
- loading screens, audio и localization;
|
||
- server maps, collision, pathfinding/mmaps/vmaps;
|
||
- DB records и scripts.
|
||
|
||
`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:
|
||
|
||
```text
|
||
base → core compatibility → project dependencies → user project → local dev override
|
||
```
|
||
|
||
Конфликт разрешается декларативным priority/dependency rule и показывается в build report. Для коллекций предпочтительны semantic merge operations, а не копирование целой upstream-таблицы.
|
||
|
||
## Сборка и публикация
|
||
|
||
Pipeline: `inspect → import → validate → compile → bake → diff → package → verify → publish`.
|
||
|
||
Каждый шаг:
|
||
|
||
- детерминирован при одинаковых входах;
|
||
- кешируется по content hash;
|
||
- пишет structured diagnostics;
|
||
- не публикует частичный результат;
|
||
- доступен из Godot Editor и headless CI.
|
||
|
||
## Миграции форматов
|
||
|
||
Каждая схема имеет monotonically increasing version. Loader либо мигрирует старую версию с backup, либо открывает read-only. Migration имеет fixture `before → after`, проверку idempotence и documented loss policy.
|
||
|
||
## Локализация
|
||
|
||
Текст хранится по locale, отдельно от логики. Validator проверяет placeholders, plural/gender conventions, длины UI, отсутствующие переводы и orphan keys. Fallback locale задаётся профилем и явно отображается в preview.
|
||
|
||
## Пользовательские scripts
|
||
|
||
Script assets имеют declared hooks, API version, permissions и deterministic validation. Генерация C++ skeleton для core допустима, но его сборка и deployment являются отдельным артефактом. Editor не обещает выразить любую серверную механику только через визуальный граф.
|