> For the complete documentation index, see [llms.txt](https://docs.bestway.com.ua/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bestway.com.ua/gem-rts-v1-ru/instrumentarij-gem-rts/gem-importer.md).

# GEM Importer

Руководство

**GEM Importer** преобразует входные файлы **FBX**, **OBJ**, **glTF**/**GLB** и **MDL** в набор **GEM/MDL** output-файлов.

**Способы запуска программы:**

1. Двойным щелчком по `gem_import.exe`. \
   Программа работает согласно настройкам из конфигурационного файла  `gem_import.json`.
2. [Из командной строки](#user-content-fn-1)[^1]. \
   Этот способ позволяет передавать параметры для конкретного запуска программы без перезаписи конфигурационного файла `gem_import.json`.

## Первый запуск

{% hint style="info" %}
**Первый запуск** программы подразумевает, что в папке c `gem_import.exe` **отсутствует** конфигурационный файл `gem_import.json`.
{% endhint %}

При первом запуске **GEM Importer** создаёт базовый файл конфигурации `gem_import.json` в папке с `gem_import.exe` и завершает работу. 

Первый запуск осуществляется двойным кликом по `gem_import.exe` или из **командной строки** без указания параметров \[`gem_import`].

{% hint style="warning" %}
Импорт файлов во время первого запуска не выполняется.
{% endhint %}

## Приоритет источников настроек

Итоговые значения параметров импорта формируются из трёх источников. Каждый следующий источник имеет более высокий приоритет и переопределяет соответствующие значения из предыдущего источника:

1. Встроенные значения по умолчанию;
2. Секции из `gem_import.json`;
3. Явные CLI-переопределения.

{% hint style="info" %}
Параметры командной строки применяются только для текущего запуска и не изменяют содержимое `gem_import.json`.
{% endhint %}

## Настройка `gem_import.json`

Файл `gem_import.json` является основным способом настройки GEM Importer. После первого запуска откройте созданный файл в текстовом редакторе и укажите параметры импорта. При последующих запусках двойным щелчком программа использует настройки из этого файла.

<details>

<summary>Пример <code>gem_import.json</code></summary>

```json
{
  "app": {
    "version": 2,
    "importer": "gem_import 1.0.0.110",
    "description": "Configuration for importing and exporting GEM/MDL assets",
    "author": "gem_import",
    "debug": {
      "outLog": "./out_log",
      "verbose": 1,
      "htmlFormat": false,
      "dryRun": false
    }
  },
  "import": {
    "general": {
      "inputDir": "./in",
      "outDir": "./out",
      "importUniformScale": 1.0
    },
    "content": {
      "volumes": true
    },
    "overwriteExisting": {
      "mesh": true,
      "texture": true,
      "animation": true,
      "material": true,
      "cmesh": true,
      "def": true,
      "mdl": true
    },
    "textures": {
      "searchPaths": [],
      "textureOutputSubdir": "",
      "useTexturesFromModel": true,
      "fileNameConvention": {
        "diffuse": ["basecolor", "base_color", "albedo", "diffuse"],
        "bump": ["normal", "normalmap", "normal_pbr", "bump", "nm"],
        "ao": ["ao", "ambientocclusion", "cavity"],
        "roughness": ["roughness", "rough", "rg"],
        "metallic": ["metallic", "metalness", "metal", "met", "mt"],
        "specular": ["specular", "spec", "sp"],
        "glossiness": ["gloss", "glossiness"],
        "emissive": ["emissive", "emission", "emit"],
        "fuzz": ["fuzz"]
      }
    },
    "materials": {
      "classSimple": "pbr/simple",
      "classStandard": "pbr/standard",
      "classStandardEmissive": "pbr/standard_emissive",
      "defaultNormal": "$/nmap_flat",
      "defaultAo": "$/white",
      "defaultRoughness": "$/white",
      "defaultMetallic": "$/black"
    }
  }
}
```

</details>

### Таблица ключей `gem_import.json`

<table><thead><tr><th width="236.0703125">Секция</th><th width="208.8046875">Ключ</th><th>Назначение</th></tr></thead><tbody><tr><td><code>app.debug</code></td><td><code>outLog</code></td><td>Указание на папку логов</td></tr><tr><td><code>app.debug</code></td><td><code>verbose</code></td><td>Степень подробности файлового лога [0..2]</td></tr><tr><td><code>app.debug</code></td><td><code>htmlFormat</code></td><td>Записывать лог импорта в формате HTML, вместо TXT</td></tr><tr><td><code>app.debug</code></td><td><code>dryRun</code></td><td>Включает режим чтения/валидации без обычной записи результата</td></tr><tr><td><code>import.general</code></td><td><code>inputDir</code></td><td>Указание пути к исходной папке с  файлами для импорта. <br>Входные папки для <code>--run-config</code></td></tr><tr><td><code>import.general</code></td><td><code>outDir</code></td><td>Указание пути к корневой папке результата импорта</td></tr><tr><td><code>import.general</code></td><td><code>importUniformScale</code></td><td>Задает scale для импортируемых моделей</td></tr><tr><td><code>import.content</code></td><td><code>volumes</code></td><td>Если выставлен, то импортер будет сохранять и экспортировать найденный volume/collision content в MDL и <code>.cmesh</code></td></tr><tr><td><code>import.overwriteExisting</code></td><td><p><code>mesh</code>, </p><p><code>texture</code>, </p><p><code>animation</code>, </p><p><code>material</code>, </p><p><code>cmesh</code>, </p><p><code>def</code>,</p><p><code>mdl</code></p></td><td>Разрешение перезаписывать уже существующие output-файлы указанных типов</td></tr><tr><td><code>import.textures</code></td><td><code>searchPaths</code></td><td>Дополнительные папки поиска исходных текстур</td></tr><tr><td><code>import.textures</code></td><td><code>textureOutputSubdir</code></td><td>Относительная подпапка внутри <code>outDir</code> для экспортированных текстур. Если значение пустое, то текстуры будут писаться рядом с моделью</td></tr><tr><td><code>import.textures</code></td><td><code>useTexturesFromModel</code></td><td><ul><li><code>true</code>  - брать texture-ссылки из source material; </li><li><code>false</code>  - собирать material textures из папок, названных именами материалов</li></ul></td></tr><tr><td><code>import.textures</code></td><td><code>fileNameConvention</code></td><td>Привязка суффиксов имён файлов к полям <code>.material</code> для режима <code>useTexturesFromModel=false</code></td></tr><tr><td><code>import.materials</code></td><td><code>classSimple</code>, <code>classStandard</code>, <code>classStandardEmissive</code></td><td>Классы генерируемых MDL-materials</td></tr><tr><td><code>import.materials</code></td><td><code>defaultNormal</code>, <code>defaultAo</code>, <code>defaultRoughness</code>, <code>defaultMetallic</code></td><td>Fallback textures для генерируемых материалов</td></tr></tbody></table>

### Обработка геометрии

Импортёр автоматически учитывает особенности систем координат входных форматов и выполняет преобразования, необходимые для GEM/MDL output. Для FBX и OBJ нормали генерируются только в том случае, если они отсутствуют в исходной модели.

Двухсторонность полигонов не настраивается через JSON.&#x20;

* Для GLB/GLTF сохраняется `doubleSided` исходного материала.&#x20;
* Для FBX учитываются material two-sided и явно заданный у узла `CullingOff/CullingOn`.
* Сабмеш без привязки к материалу принудительно получает `twoSided=true`.

Установка `content.volumes=true` не создаёт **volumes** из ничего. Флаг разрешает сохранить и записать volumes, которые importer распознал в исходной модели.&#x20;

* При `false` volume-ресурсы и элементы `.cmesh` удаляются перед записью.&#x20;
* Перезапись уже существующего `.cmesh` независимо контролируется через `overwriteExisting.cmesh`.

### Флаг `overwriteExisting`

Флаги `overwriteExisting` не отключают экспорт нового файла. Они защищают только уже существующие файлы. Алгоритм отработки следующий:

* если файла ещё нет -> файл пишется;
* если файл уже есть -> файл пишется только при `overwriteExisting.<type> = true`.

Параметр необходим, чтобы не перезаписывать уже существующие и настроенные  `.def` и `.mdl` файлы при повторном импорте модели.

<details>

<summary>Пример настроек секции <code>overwriteExisting</code> </summary>

```json
"overwriteExisting": 
    { 
    "mesh": true, 
    "texture": true, 
    "animation": true, 
    "material": true, 
    "cmesh": true, 
    "def": false, 
    "mdl": false
    }
```

</details>

### Обработка текстур

Значение параметра  `searchPaths`  задает путь поиска исходных текстур. Он используется в том числе для внешних картинок `.gltf`.

Значение параметра  `textureOutputSubdir`  задает output-подпапку для экспортированных текстур внутри `outDir`.

Тогда модель пишется в папку `<outDir>/<model_stem>/`**,** \
а текстуры пишутся в папку `<outDir>/textures/<model_stem>/`

Если `textureOutputSubdir` пустой, текстуры пишутся рядом с моделью.

<details>

<summary>Пример настройки секции <code>textures</code></summary>

```json
"textures": 
    { 
    "searchPaths": ["D:/SourceTextures/Rock"], 
    "textureOutputSubdir": "textures", 
    "useTexturesFromModel": true, 
    "fileNameConvention": 
        { 
        "diffuse": ["basecolor", "base_color", "albedo", "diffuse"], 
        "bump": ["normal", "normalmap", "normal_pbr", "bump", "nm"], 
        "ao": ["ao", "ambientocclusion", "cavity"], 
        "roughness": ["roughness", "rough", "rg"], 
        "metallic": ["metallic", "metalness", "metal", "met", "mt"], 
        "specular": ["specular", "spec", "sp"], 
        "glossiness": ["gloss", "glossiness"], 
        "emissive": ["emissive", "emission", "emit"], 
        "fuzz": ["fuzz"] 
        }
    }
```

</details>

### Параметр `useTexturesFromModel`

1. Обычный режим (настройки по умолчанию):

```json
"useTexturesFromModel": true
```

Importer берёт texture-ссылки из source material: FBX material slots, OBJ .mtl, или glTF/GLB materials.

2. Альтернативный режим:

```json
"useTexturesFromModel": false
```

Importer игнорирует texture-ссылки внутри модели и ищет папки материалов рядом с исходной моделью, а также непосредственно внутри каждой папки из `searchPaths`.

Без `searchPaths`:

```
model_folder/
    model.fbx
    <materialName>/
        <anything>_<textureType>.<ext>
```

Если нужен дополнительный уровень `textures`, его надо явно указать относительно папки модели:

```json
"searchPaths": ["textures"]
```

```
model_folder/
    model.fbx
    textures/
        <materialName>/
            <anything>_<textureType>.<ext>
```

Для абсолютного `searchPaths` используется та же схема:

```
<materialName>/
    <anything>_<textureType>.<ext>
```

Пример для material `matid_1`:

```
matid_1/
    rock_basecolor.jpg
    rock_normal.jpg
    rock_ao.jpg
    rock_roughness.jpg
```

Постфиксы типов настраиваются в секции  `import.textures.fileNameConvention`:

```json
"fileNameConvention": 
    { 
    "diffuse": ["basecolor", "base_color", "albedo", "diffuse"], 
    "bump": ["normal", "normalmap", "normal_pbr", "bump", "nm"],
    "ao": ["ao", "ambientocclusion", "cavity"],
    "roughness": ["roughness", "rough", "rg"],
    "metallic": ["metallic", "metalness", "metal", "met", "mt"],
    "specular": ["specular", "spec", "sp"],
    "glossiness": ["gloss", "glossiness"], 
    "emissive": ["emissive", "emission", "emit"],
    "fuzz": ["fuzz"]
    }
```

Ключом является поле/slot в генерируемом `.material`. \
Значение ключа представляет собой  список допустимых суффиксов после последнего знака нижнего подчеркивания \[ `_` ] в имени файла. \
Имя непосредственной родительской папки должно совпадать с именем материала (файлы в папке другого материала игнорируются).

{% hint style="info" %}
Импортёр сравнивает только часть имени после последнего знака нижнего подчеркивания \[ `_` ].  Поэтому составные значения со знаками нижнего подчеркивания, например `base_color` и `normal_pbr`, не распознаются. Используйте односоставные варианты `basecolor`, `normal` или `normalmap`.
{% endhint %}

{% hint style="info" %}
В режиме `useTexturesFromModel=false` имена экспортированных `.dds` и ссылки на них внутри `.material` записываются в lowercase. Это обеспечивает точное совпадение путей на case-sensitive файловых системах, включая Linux.
{% endhint %}

<details>

<summary>Пример неправильной настройки параметра</summary>

Если в конфигурационном файле указано\
&#x20;`"bump": ["normal","normalmap","normal_pbr","bump","nm"]`,

то файлы&#x20;

`matid_1/rock_normal.png`&#x20;

и

&#x20;`matid_1/rock_normalmap.png`&#x20;

при импорте оба попадут в поле `bump`.

</details>

## Параметры командной строки

Параметры командной строки позволяют изменить настройки для конкретного запуска GEM Importer. Переданные значения имеют приоритет над соответствующими значениями из `gem_import.json`, но не изменяют содержимое файла конфигурации.

<table><thead><tr><th width="233.48046875">Параметр</th><th>Назначение</th></tr></thead><tbody><tr><td>Без параметров</td><td>Создать конфигурационный файл с базовыми настройками импорта   <code>gem_import.json</code> и завершить работу (при первом запуске программы).<br>Если <code>gem_import.json</code> существует, то <br>запустить импорт файлов согласно настройкам конфигурационного файла </td></tr><tr><td><code>-i, --input &#x3C;file></code></td><td>Один входной файл.<br>Поддерживаются форматы <code>.fbx</code>, <code>.obj</code>, <code>.gltf</code>, <code>.glb</code>, <code>.mdl</code></td></tr><tr><td><code>--input-dir &#x3C;dirs></code></td><td>Одна или несколько входных папок; пути разделяются с помощью знака точки с запятой [ <code>;</code> ]</td></tr><tr><td><code>--run-config</code></td><td>Импортировать из <code>import.general.inputDir</code></td></tr><tr><td><code>-s, --settings &#x3C;file></code></td><td>Использовать указанный <code>gem_import.json</code></td></tr><tr><td><code>-o, --out-dir &#x3C;dir></code></td><td>Корневая папка результата; переопределяет <code>import.general.outDir</code></td></tr><tr><td><code>--verbose [0 | 1 | 2 ]</code></td><td>Задает уровень подробности лог-файла</td></tr><tr><td><code>--html</code><br><code>--no-html</code></td><td>Писать HTML-лог<br>Писать TXT-лог</td></tr><tr><td><code>--dry-run</code></td><td>Только чтение/валидация, без записи обычного результата</td></tr><tr><td><code>--write-help</code></td><td>Записать <code>gem_import.md</code> рядом с executable</td></tr><tr><td><code>--version</code></td><td>Показать версию <code>gem_import</code> и завершить работу</td></tr><tr><td><code>-h, --help</code></td><td>Показать консольную справку</td></tr></tbody></table>

### Запуск с помощью BAT-файла

Для регулярного запуска **GEM Importer** с одинаковыми параметрами можно создать BAT-файл. Команду не потребуется вводить вручную при каждом запуске.

Создайте текстовый файл в папке с `gem_import.exe`, добавьте в него команду запуска и сохраните файл с расширением `.bat`, например `import_models.bat`:

```bat
@echo off
gem_import --input-dir "D:\Models\fbx;D:\Models\gltf" --out-dir "D:\Out" --verbose 1
pause
```

Для выполнения команды дважды щёлкните по созданному BAT-файлу. Команда `pause` оставляет окно командной строки открытым после завершения импорта, чтобы можно было проверить сообщения программы.

<details>

<summary>Примеры запуска из командной строки</summary>

{% hint style="info" %}
Все приведённые ниже команды вводятся в командной строке Windows.
{% endhint %}

1. Импорт одного файла:

```bash
gem_import --input "D:\Models\vehicle.fbx" --out-dir "D:\Out" --verbose 2 --html
```

Команда импортирует файл `vehicle.fbx`, сохраняет результат в папку `D:\Out` и записывает расширенный лог в формате HTML.

2. Импорт файлов из нескольких папок:

```bash
gem_import --input-dir "D:\Models\fbx;D:\Models\gltf" --out-dir "D:\Out" --verbose 1
```

Команда импортирует поддерживаемые файлы из папок `D:\Models\fbx` и `D:\Models\gltf`. Пути к папкам разделяются точкой с запятой. Результат сохраняется в `D:\Out`, для файлового лога используется уровень подробности 1.

3. Импорт по указанному файлу конфигурации:

```bash
gem_import --run-config --settings "D:\Work\gem_import.json"
```

Команда использует файл `D:\Work\gem_import.json` и импортирует файлы из папок, указанных в `import.general.inputDir`.

</details>

## Результат импорта (output files)

Типичным результатом импорта является набор файлов:

```
<outDir>/
    <model_stem>/
        <model_stem>.def
        <model_stem>.mdl
        .mesh
        .cmesh
        .material
        .animation
        *.dds
```

{% hint style="info" %}
Набор файлов зависит от исходной модели и от того, есть ли соответствующие данные.
{% endhint %}

[^1]: Чтобы открыть окно командной  строки в Windows проделайте следующие действия:

    1. Откройте в Проводник
    2. Установите курсор в адресную строку Проводника.
    3. Введите `cmd` и нажмите Enter.