# Руководство AstraDroneSim

## Первый запуск
Войдите в локальный профиль или создайте новый. Пароль не отправляется на сервер.
Подключите пульт USB-кабелем с передачей данных. RadioMaster/EdgeTX: USB Joystick;
FlySky: совместимый USB-режим или simulator adapter. Затем откройте «Управление».

## Калибровка
Выберите устройство, проверьте сырые каналы, нажмите «Мастер калибровки».
По запросам установите центр, пройдите весь ход каждой оси и подтвердите направление.
Крен вправо — наклон вправо; тангаж вперёд — нос вниз. Газ должен показывать 0% в нулевом положении.
Для геймпада включите «Нулевой газ в центре стика»: нижняя половина тоже даёт ноль.
После изменения режима газа повторите калибровку. Сохраните настройки профиля.

## Функции пульта
В нижней части страницы управления назначьте Arm, переключение режима, сброс,
стрелки, таблицу результатов, камеру тренера и выбор пилота.
Можно выбрать кнопку либо крайнее положение AUX-оси (+50% / −50%).
Рядом с осью или функцией есть «Определить»: нажмите, переместите нужный канал и удержите его. Автовыбор не меняет инверсию и диапазон. При необходимости повторите калибровку.
Номера в интерфейсе начинаются с 1. Не назначайте разные функции одному переключателю.
Функции работают по переходу в активное положение: для повторного действия верните переключатель назад.
Удерживаемая при подключении кнопка не включает моторы. Arm разрешён только при газе ниже 8%.
После отключения пульта/потери фокуса потребуется новый Arm.
Трёхпозиционный тумблер: назначьте крайние положения на Angle и Acro;
среднее положение AUX-оси (±25%) назначьте на Horizon. Каждый режим включается при входе в своё положение.

## Превью
Превью в настройках рассчитывает ориентацию виртуального дрона на основании стиков и режима.
Оранжевый луч обозначает нос. Это демонстрация ориентации, а не вид реального полёта;
Arm в меню не запускает полёт. Используются текущие рейты после их сохранения.

## Режимы
**Acro:** стик задаёт угловую скорость; при отпускании дрон сохраняет наклон.
**Angle:** стик задаёт наклон до 50°, при отпускании выполняется выравнивание.
**Horizon:** выравнивание у центра стиков, переход к Acro на краях.
Это приближённая модель, не эмуляция всей прошивки Betaflight. Начальный режим выбирается
в «Оформление и OSD», переключение — с пульта или клавишей M.

## Цвета и OSD
Раздел «Оформление и OSD» предлагает готовые темы и свои HEX-цвета фона, панелей,
текста и акцента. Нечитаемые сочетания отклоняются. «Сохранить оформление» запоминает
схему на компьютере и в активном профиле. В OSD можно скрыть скорость, высоту,
ворота, время круга, имя пульта, прицел и подсказки, изменить масштаб, сторону и цвет текста.
Название карты, состояние моторов, режим и ошибки остаются видимыми.
Цвета 3D-карты меняются в редакторе отдельно от оформления меню.

## Полёт и клавиши
Выберите карту и нажмите «Начать полёт». Пробел — Arm/Disarm, R — сброс,
M — режим, H — стрелки, L — таблица кругов, Esc — возврат в меню.
Клавиатура: стрелки — крен/тангаж, A/D — рыскание, W/S — дискретный газ.
Для полноценного полёта используйте пульт. Первые ворота запускают круг;
пройдите остальные по порядку и вернитесь к первым в правильном направлении.

## LAN и тренер
Укажите порт и отдельный ключ комнаты, запустите сервер в разделе сети.
Тренер тоже может запустить сервер и подключиться к 127.0.0.1. Кнопка «Остановить сервер» завершает комнату; закрытие приложения завершает и полёт, и сервер.
Другие компьютеры вводят IP хоста. Карта с моделями и текстурами загружается автоматически.
Тренер выбирает вид сверху, облёт, слежение, FPV или свободную камеру.
Нажмите имя пилота в таблице для слежения; C — вид, Tab — пилот.
Свободная камера: WASD, Q/E по высоте, стрелки для поворота, колесо — масштаб/скорость.
Используйте доверенную LAN; транспорт не шифруется. Обновляйте сервер и клиентов вместе.

## Редактор карт
Слева — объекты, в центре — план, справа — координаты, поворот, размеры и цвет.
ЛКМ перемещает, рамка/Ctrl выделяют группу, СКМ панорамирует, колесо масштабирует.
Ctrl+Z — отмена, Ctrl+Shift+Z — повтор, Ctrl+D — дублирование. Стрелки списка меняют порядок ворот.
Видимость и коллизия препятствий независимы. F5 — 3D-предпросмотр, Esc его закрывает.
Сохранение JSON копирует ресурсы рядом; .astramap содержит карту и ресурсы одним файлом.
GLB/glTF — только визуальная сцена: коллайдеры задаются отдельно.

## Если что-то не работает
Нет устройства: проверьте USB-режим, кабель, выбор в списке и права ОС на джойстик.
Не включаются моторы: газ ниже 8%, переключатель сначала неактивен, окно полёта в фокусе.
Реакция неверная: проверьте индикаторы, инверсию, назначения осей и повторите калибровку.
Нет соединения: проверьте IP, TCP-порт, файрвол, ключ и версии всех участников.
Ошибка полёта не закрывает меню; журнал находится в ~/.local/share/astradronesim/flight.log.
Правила для Blender/ИИ доступны вторым пунктом этой инструкции и кнопкой копирования.

## Встроенные карты и текстуры (0.5)

На странице полёта доступны 17 встроенных карт: первоначальная трасса и 16 новых локаций. В Android откройте «Карты и импорт»: карточки содержат реальные 3D-превью и сложность. В настольном редакторе у объектов и покрытия земли появился выбор текстуры. В помещениях обзорные превью показаны со снятой крышей; в полёте крыша остаётся.

Android без пульта: левый сенсорный стик — газ/рыскание, правый — крен/тангаж; кнопки сверху — ARM, режим, сброс и меню. Газ сохраняет положение после отпускания. Чтобы включить моторы, сначала опустите газ в ноль. Два стика работают одновременно (мультитач).


## Спортивные режимы (0.6)

Выберите карту нужного упражнения. Рядом с выбором карты нажмите «Инструкция режима» — откроются правила именно этой площадки. В этой справке выберите «Режимы соревнований», чтобы прочитать все инструкции. На Android откройте галерею карт или «Помощь» → «Правила режима».

F2 запускает или продолжает задание; G выполняет специальное действие (например захват груза); F фиксирует финиш после посадки с выключенными моторами. R готовит повтор в пределах числа попыток, C меняет камеру. На Android есть экранные кнопки. В настройках пульта назначьте «Старт задания», «Действие задания», «Финиш» на кнопку или AUX. Для режимов гонки и подвижных проёмов нужен ACRO.

В LAN хост или тренер запускает общий отсчёт F2. В футболе перед подключением выберите команду и роль; «Авто» распределяет свободные места. Допустимы три пилота в команде и отдельные тренеры. Для визуального пилотирования используйте внешнюю камеру. Сервер и все клиенты должны иметь версию 0.6.x (протокол 4).

Новая батарея OSD расчётная: напряжение, ток и расход показывают виртуальную модель, а не реальные измерения. Новые элементы включаются в «Оформление и OSD». Тема по умолчанию — Astra Orange.


## Запуск на Linux

Откройте ярлык AstraDroneSim или выполните `./run.sh` в папке проекта. Можно выполнить `python3 start.py`: программа сама переключится на Python из `.venv` с установленными зависимостями. Системный `python` и установка PySide6 в системный Python не нужны. Если окружение отсутствует, установите приложение через `python3 tools/install_linux.py` (Python 3.11–3.13).