# Инструменты OpenWC внутри Godot Editor

## Принцип

Все интерактивные authoring-инструменты реализуются как Godot `EditorPlugin`. Отдельный native GUI не является частью целевой архитектуры. Headless-команды допускаются для CI и batch build, но используют те же application services и validators.

## Workspace

Плагин `addons/openwc_editor` должен предоставлять:

- главное рабочее пространство World;
- docks Content Browser, Outliner, Inspector, Validation, Build, Database и History;
- viewport overlays и gizmos;
- project settings для путей и dev environments;
- command palette и контекстные действия;
- playtest launcher.

Editor UI вызывает services, а не SQL, MPQ parsers или файловую запись напрямую.

## Инструменты мира

- Camera/navigation и переход по map/tile/coordinates.
- Selection, multiselect, filtering, snapping и transform gizmo.
- Terrain sculpt: raise/lower, smooth, flatten, noise, stamp.
- Terrain paint: texture layers, alpha, holes и liquid masks.
- Placement: M2, WMO, creature, gameobject, trigger, sound emitter.
- Paths: waypoint, patrol, spline, taxi и transport preview.
- Volumes: area, subzone, encounter, graveyard, phase и weather.
- Visualization modes: collision, normals, chunk/tile bounds, nav/pathing, spawn density, quest dependencies и streaming budgets.
- Navigation overlay: walkable areas, isolated regions, off-mesh connections, path cost и unreachable selection.

Каждый stroke или placement создаёт одну логическую undoable command. Длительный stroke агрегируется, чтобы history не содержала команду на каждую вершину.

## Data editors

- Creature и gameobject templates.
- Spawn/group/path editor.
- Quest form и quest-chain graph.
- Gossip/dialogue и conditions.
- Loot/vendor/trainer/item editors.
- Dungeon/encounter graph.
- Localization table с completeness report.
- Raw server record inspector только как диагностический режим.

Инспекторы генерируются из `ContentTypeDescriptor`, но сложные сущности могут иметь специализированный inspector. Валидация отображается у поля, сущности и проекта.

## Selection и scene tree

Authoring selection хранится отдельно от runtime scene tree. Preview-ноды считаются disposable projection: их можно пересоздать из `EditorWorldModel`. Сохранение `.tscn` не является способом записи server content.

## Undo/redo и autosave

- Все мутации проходят через command history.
- Команда хранит стабильные IDs, а не ссылки на Node.
- Autosave пишет recovery journal атомарно.
- После crash предлагается восстановление с preview diff.
- External file changes обнаруживаются; конфликт не перезаписывается автоматически.

## Длительные задачи

Import, bake, validation, packaging и DB snapshot выполняются как jobs:

- progress и текущий этап;
- cancellation token;
- структурированные diagnostics;
- отсутствие блокировки editor UI;
- staging output и атомарная публикация результата;
- повторяемая команда для headless CI.

Navmesh bake через `recast-rs` оформляется таким же cancellable job: Editor экспортирует каноническую triangle geometry во staging, запускает pinned CLI/backend, импортирует versioned navigation artifact и показывает diagnostics. Preview-ноды navmesh не сохраняются как источник истины.

## Navigation validation

Первый navigation backend — optional `recast-rs`. Он используется для:

- проверки пути от quest giver к objectives и turn-in;
- поиска NPC/gameobject вне walkable polygon;
- проверки patrol/escort paths;
- проверки связности входов, дверей и encounter rooms;
- визуализации area costs, holes и off-mesh connections.

Профиль bake хранит версию backend и параметры agent radius/height/climb, cell size/height, slope, region и tile size. Изменение профиля инвалидирует navigation cache. Отсутствие backend не должно мешать редактированию, но navigation-dependent validation помечается как `Not run`.

## Database dock

- Показывает тип ядра, revision, schema version и capabilities.
- По умолчанию read-only.
- Production target визуально и технически отделён от dev.
- Перед apply показывает SQL/change diff, preconditions и backup status.
- Secrets не сохраняются в проект и не попадают в output/log.

## Playtest

Редактор должен уметь:

1. проверить Content Project;
2. собрать client assets и server change set;
3. применить change set к disposable/dev environment;
4. запустить или перезапустить core при необходимости;
5. запустить клиент на нужной карте и позиции;
6. собрать client/server logs и test observations;
7. откатить временный change set.

Fast preview без сервера допускается для геометрии, освещения, spawn layout и quest graph, но НЕ считается проверкой серверной механики.

## Расширения редактора

Новый тип контента регистрирует schema, icon, inspector, validator, compiler и optional viewport presenter. Плагин обязан объявить версию API и зависимости. Неизвестное поле сохраняется round-trip, если формат это допускает.

## UX-принципы

- Безопасные значения по умолчанию и preview перед разрушительной операцией.
- Ошибка объясняет проблему, местоположение и действие для исправления.
- Stable IDs видны, но пользователь в основном работает с именами и ссылками.
- Bulk-edit показывает scope и итоговый diff.
- Горячие клавиши переназначаются.
- Цвет не является единственным носителем статуса.
- Основные сценарии доступны без ручного SQL.

## MVP

Первый editor slice: открыть карту, импортировать server snapshot, увидеть spawns, поставить NPC, создать простой kill quest, проверить ссылки, получить SQL diff, применить к dev-базе и запустить playtest.
