open-wc/docs/CONTENT_AND_SERVER_DATA.md

Контент, клиентские данные и серверная БД

Источник истины

Пользовательские изменения хранятся в Content Project. Original client data и server DB являются импортируемыми upstream-источниками; generated cache, SQL и packages являются build artifacts.

upstream snapshot + user content + build profile → validated artifacts

Структура Content Project

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:

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 не обещает выразить любую серверную механику только через визуальный граф.