open-wc/docs/GODOT_EDITOR.md

Инструменты 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.