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

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

Пользовательские изменения хранятся в 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 общей версией. Клиент не входит в мир при несовместимой обязательной версии пакета без понятной диагностики.

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