# Развертывание симуляции зоны ЧС в Unity 

Если в процессе установки и развертывания симуляции возникли неописанные в инструкции ошибки, то, возможно, решение появившейся проблемы описано в [последнем разделе](https://git.robofob.ru/sirius/sirius_unity_sim#%D0%B8%D0%B7%D0%B2%D0%B5%D1%81%D1%82%D0%BD%D1%8B%D0%B5-%D0%BF%D1%80%D0%BE%D0%B1%D0%BB%D0%B5%D0%BC%D1%8B-%D0%B8-%D0%B8%D1%85-%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D1%8F) этой инструкции.

Требования к системе прописаны на [сайте](https://docs.unity3d.com/6000.0/Documentation/Manual/system-requirements.html), дублирую ниже:

> RAM должна быть не меньше 8 Гб

| Operating system 	| Operating system version                                                                             	| CPU                                                                                                                       	| Graphics API                                       	| Additional requirements                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          	|
|------------------	|------------------------------------------------------------------------------------------------------	|---------------------------------------------------------------------------------------------------------------------------	|----------------------------------------------------	|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------	|
| Windows          	| Windows 10 version 21H1 (build 19043) or newer (X64), Windows 11 21H2 (build 22000) or newer (Arm64) 	| X64 architecture with SSE2 instruction set support, Arm64                                                                 	| DX10, DX11, DX12 or Vulkan capable GPUs            	| Hardware vendor officially supported drivers                                                                                                                                                                                                                                                                                                                                                                                                                                                                     	|
| macOS            	| Big Sur 11 or newer                                                                                  	| X64 architecture with SSE2 instruction set support (Intel processors)  Apple M1 or above (Apple silicon-based processors) 	| Metal-capable Intel and AMD GPUs                   	| Apple officially supported drivers (Intel processor)   Rosetta 2 is required for Apple silicon devices running on either Apple silicon or Intel versions of the Unity Editor                                                                                                                                                                                                                                                                                                                                     	|
| Linux            	| Ubuntu 22.04, Ubuntu 24.04                                                                           	| X64 architecture with SSE2 instruction set support                                                                        	| OpenGL 3.2+ or Vulkan-capable, Nvidia and AMD GPUs 	| Gnome desktop environment running on top of X11 or Wayland windowing  system, Nvidia official proprietary graphics driver, or AMD Mesa  graphics driver. Other configurations and user environments as provided  with the supported distribution (Kernel, Compositor, etc.)<br><br>Notes:<br>•  Ubuntu 22.04:  Wayland is supported with AMD graphics cards.<br>•  Ubuntu 24.04:  Wayland is supported with AMD graphics cards and Nvidia graphics cards  utilizing Nvidia proprietary graphics drivers 550 and above. 	|

# 1. Установка UnityHub

Установка лаунчера подробно описано [на официальном сайте](https://docs.unity.com/en-us/hub/install-hub-linux#install-the-hub-on-an-ubuntu-linux-distribution). Дублирую информацию:

1.1 Проверяем наличие утилиты curl или при необходимости устанавливаем ее:
```
sudo apt install curl
```
1.2 Добавляем публичный ключ для подписи
```
sudo install -d /etc/apt/keyrings
curl -fsSL https://hub.unity3d.com/linux/keys/public | sudo gpg --dearmor -o /etc/apt/keyrings/unityhub.gpg
```
1.3 Добавляем репозиторий Unity Hub (только для x86_64/amd64)
```
echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/unityhub.gpg] https://hub.unity3d.com/linux/repos/deb stable main" | sudo tee /etc/apt/sources.list.d/unityhub.list
```
1.4 Устанавливаем приложение
```
sudo apt update
sudo apt install unityhub
```
# 2. Установка Unity

Заходим в Unityhub и во вкладке `Installs` нажимаем `Install Editor`. В появившимся окне выбираем `Unity 6000.0.77`, проверяем, достаточно ли свободного места на диске, никакие дополнительные модули не ставим и подтверждаем установку. При необходимости модули можно будет доставить потом.

> Разработка среды велась на движке `Unity 6000.0.77f1`, если на данный момент эта версия не доступна, а клиент предлагает поставить версию `6000.0.+`, то выбираем ее. При первом запуске проекта откроется меню, которое сообщит вам об отстутсвии указанной версии, в разделе `Installs` выбираем установленную версию и открываем проект в более новой версии. Сразу после выскочит сообщение о том, что часть настроек проекта из-за более актуальной версии придется изменить, выбираем `Continue`

# 3. Развертывание симуляции

1. Склонировать симуляцию из [Git‑репозитория](https://git.robofob.ru/sirius/sirius_unity_sim.git) в любую удобную папку на диске:
> Скачиваем сначала без подпроекта `unity_robotics`, т.к. его нужно ставить после установки доп. пакетов через `Package Manager` в Unity (через меню `Window > Package manager`), иначе первый запуск симуляции может надолго застрять на стадии компиляции.
Рабочим воркспейсом будем считать `~/sirius_ws`.
```bash
cd ~/sirius_ws
git clone https://git.robofob.ru/sirius/sirius_unity_sim.git
```

2. Скачиваем модели мира [Industrial_Zone_Modular_Pack](https://disk.yandex.ru/d/leNWr7JXhXlNJQ), [AllSkyFree](https://disk.yandex.ru/d/WjRCJTkRmQfaCQ), [Vefects](https://disk.yandex.ru/d/pohMh5mcrlVngA) и разархивируем их в папку `Assets`. Должна получится струткура:
```
Assets/
├─ AllSkyFree/
├─ Industrial_Zone_Modular_Pack/
├─ Vefects
└─ ...
```
3. В UnityHub добавляем проект `Add new project` и выбираем папку `sirius_unity_sim`.
> При возникновении ошибки `...failed to initialize unity graphics...` должна помочь перезагрузка ПК. Если не помогло, то гугл в помощь.
4. Открываем проект и ждем процесса компиляции проекта. Для успешного завершения компилции Unity не хватает некоторых пакетов, из-за чего система предложит перейти в режим `Safe Mode`. Соглашаемся.
> При запросе Unity на обновление собственного(ых) пакета(ов) следуйте предоставленным инструкциям.

> Если по каким-то причинам все скомпилилось удачно, то это значит, что у вас уже есть недостающие пакеты. Переходите к п.№6
5. После открытия программы устанавливаемя дополнительные пакеты для организации свзяи ROS+Unity:
    - Через меню `Window > Package manager` выбрать раздел `Unity Registry` и установить библиотеку `Mathematics`,`Burst`: вбить в поисковике название, выбрать нужный проект и в открывшемся описании пакета нажать `Install`, если вместо нее отображается кнопка `Remove`, значит, пакет уже установлен.
    - Через интерфейс "+" выбрать `Add package from git URL...` и ввести прикрепленные ниже ссылки
      - [ROS-TCP-Connector](https://github.com/Unity-Technologies/ROS-TCP-Connector) - перессылка сообещинй из ROS в Unity и обратно
`https://github.com/Unity-Technologies/ROS-TCP-Connector.git?path=/com.unity.robotics.ros-tcp-connector`.
      - Visualizations -  визуализация данных ROS-сообщений в Unity в реальном времени
`https://github.com/Unity-Technologies/ROS-TCP-Connector.git?path=/com.unity.robotics.visualizations`
      - [URDF-Importer](https://github.com/Unity-Technologies/URDF-Importer) 
`https://github.com/Unity-Technologies/URDF-Importer.git?path=/com.unity.robotics.urdf-importer#v0.5.2`
6. Докачиваем подпроект `unity_robotics`:
```bash
cd ~/sirius_ws
git submodule init
git submodule update
```
Ждем компиляции симуляции (для этого сделайте окно Unity активным).

7. Если Unity самостоятельно не вышел из безопасного режима, то выходим вручную `Safe Mode > Exit Safe Mode`.
8. Проверяем, что во вкладке `Robotics > ROS Settings` выбран протокол `ROS2`. Если нет, то выбираем `ROS2` и ждем компиляции проекта. По заверщении все критические ошибки должны исчезнуть.

# 4. ROS2: установка дополнительных пакетов

1. В `sirius_ws/src` клонируем пакет [ROS TCP Endpoint](https://github.com/Unity-Technologies/ROS-TCP-Endpoint):
```bash
cd ~/sirius_ws/src
git clone -b main-ros2 https://github.com/Unity-Technologies/ROS-TCP-Endpoint.git
```

2. Собираем workspace из его корня командой
```bash
cd ~/sirius_ws
colcon build --symlink-install
```

В симуляции используются сообщение пользовательского типа [LocationsOnMesh](https://git.robofob.ru/sirius/gen_locations_on_mesh), поэтому для корректной работы симуляции этот тип сообщения должен быть предварительно скомпилирован на стороне ROS2.

# 5. Запуск симуляции

1. На стороне ROS2 запускает TCP-сервер:
```bash
ros2 run ros_tcp_endpoint default_server_endpoint --ros-args -p ROS_IP:=127.0.0.1
```
2. Отрыть проект `sirius_sim` и в файлах проекта (вкладка `Project` в нижней части экрана) открыть сцену `main.unity`, которая распологается в папке `Assets/Scenes`.
3. В Unity запускаем симуляцию нажав кнопку `Play` (внешний вид: ▶) на панели инструментов (чуть выше окна просмотра сцены `Scene` / игрового окна `Game`). 
> В верхнем левом углу игрового окна будет отображаться плашка с указанием IP-адреса и индикацией состояния подключения (внешний вид: ⇄): если стрелки <span style="color:red">красного цвета</span> - соединения нет, если <span style="color:blue">синего</span> - есть, <span style="color:yellow">жетлого</span> - есть соединение, но с проблемами (игнорируем). Ошибки работы симуляции будут выводиться в собственную консоль Unity. Для прекращения работы симуляции повторно нажмите кнопку `Play`.

> Во время симуляции можно изменять параметры скриптов, положение объектов и другие элементы, но после ее завершения все изменения автоматически откатятся к начальному состоянию.

## 🚨 Известные проблемы и их решения

### ▪️ Проблема импорта текстур

При импроте текстур и материалов может возникнуть конфликт при рендеринге: предметы на сцене будут ярко розового цвета. Для устранения этой проблемы перейдите в строке меню наверху:<br>
`Edit > Render Pipeline > Universal Render Pipeline > Upgrade Project Materials to URP Materials или Upgrade Selected Project Materials to URP Materials` (второй вариант доступен при предварительном выборе проблемных текстур перед вызовом контекстного меню).

### ▪️ Ошибка компиляции библиотеки URDF-Importer `DllNotFoundException: libdl.so`
> [Похожее Issue](https://github.com/Unity-Technologies/URDF-Importer/issues/224)

Полный текст ошибки:
```console
DllNotFoundException: libdl.so assembly:<unknown assembly> type:<unknown type> member:(null)
Assimp.Unmanaged.UnmanagedLibrary+UnmanagedLinuxLibraryImplementation.NativeLoadLibrary (System.String path) (at <d40f2b0ad6814d4c8094142d8473733f>:0)
Assimp.Unmanaged.UnmanagedLibrary+UnmanagedLibraryImplementation.LoadLibrary (System.String path) (at <d40f2b0ad6814d4c8094142d8473733f>:0)
Assimp.Unmanaged.UnmanagedLibrary.LoadLibrary (System.String libPath) (at <d40f2b0ad6814d4c8094142d8473733f>:0)
Assimp.Unmanaged.UnmanagedLibrary.LoadLibrary () (at <d40f2b0ad6814d4c8094142d8473733f>:0)
Assimp.AssimpUnity.InitializePlugin () (at ./Library/PackageCache/com.unity.robotics.urdf-importer@4ed58f8d00fe/Runtime/UnityMeshImporter/Plugins/AssimpNet/AssimpUnity.cs:147)
```
Чтобы устранить эту ошибку, выполните следующие шаги:
1. Проверить наличие файла `libdl.so.2` в директории `/usr/lib/x86_64-linux-gnu`.
2. Если имеется, то добавить ссылку командой `sudo ln -s /usr/lib/x86_64-linux-gnu/libdl.so.2 /usr/lib/libdl.so`.
3. Если нет то найти и модифицировать команду из п.2.
4. Повторно открыть проект.