GEM Importer

Quick Guide

GEM Importer converts input FBX, OBJ, glTF/GLB, and MDL files into a set of GEM/MDL output files.

The program can be launched in two ways:

1. Double-click gem_import.exe. The program runs according to the settings in the gem_import.json configuration file.

2. From the command line. This method allows you to pass parameters for a specific run without modifying the gem_import.json configuration file.

First run

The first run means that the gem_import.json configuration file is not present in the folder containing gem_import.exe.

On the first run, GEM Importer creates a basic gem_import.json configuration file in the folder containing gem_import.exe and then exits.

To perform the first run, either double-click gem_import.exe or run the program from the command line without any parameters [gem_import].

No files are imported during the first run.

Configuration source precedence

The final import parameter values are determined from three sources. Each subsequent source has higher priority and overrides the corresponding values from the previous source:

1. Built-in default values;

2. Sections in gem_import.json;

3. Explicit CLI overrides.

Command-line parameters apply only to the current run and do not modify the contents of gem_import.json.

Configuring gem_import.json

The gem_import.json file is the primary way to configure GEM Importer. After the first run, open the generated file in a text editor and specify the import parameters. On subsequent launches by double-clicking, the program uses the settings from this file.

Example gem_import.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",
      "format": "MDL3",
      "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"],
        "lightmap": ["lm", "lightmap", "lightingmap"],
        "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",
      "classStandardLightmap": "pbr/standard_lightmap",
      "classStandardEmissive": "pbr/standard_emissive",
      "defaultNormal": "$/pbr/0_nm",
      "defaultAo": "$/pbr/0_ao",
      "defaultRoughness": "$/pbr/0_rg",
      "defaultMetallic": "$/pbr/0_met"
    }
  }
}

gem_import.json key reference

Section	Key	Description
app.debug	outLog	Path to the log folder
app.debug	verbose	File log verbosity level [0..2]
app.debug	htmlFormat	Write the import log in HTML format instead of TXT
app.debug	dryRun	Enables read and validation mode without writing the regular output
import.general	inputDir	Path to the source folder containing files to import. Input folders used by --run-config
import.general	outDir	Path to the root import output folder
import.general	format	Specifies the target MDL format for the imported model. Available values: • MDL1 — for GEM1. • MDL2 — for GEM2. • MDL3 — for GEM RTS.
import.general	importUniformScale	Scale applied to imported models
import.content	volumes	When enabled, the importer preserves and exports detected volume/collision content to MDL and .cmesh
import.overwriteExisting	mesh, texture, animation, material, cmesh, def, mdl	Allows existing output files of the specified types to be overwritten
import.textures	searchPaths	Additional folders in which to search for source textures
import.textures	textureOutputSubdir	Relative subfolder inside outDir for exported textures. If the value is empty, textures are written next to the model
import.textures	useTexturesFromModel	true — use texture references from the source material; false — collect material textures from folders named after the materials
import.textures	fileNameConvention	Maps filename suffixes to .material fields when useTexturesFromModel=false
import.materials	classSimple, classStandard, classStandardLightmap classStandardEmissive	Classes of the generated MDL materials
import.materials	defaultNormal, defaultAo, defaultRoughness, defaultMetallic	Fallback textures for generated materials

Geometry processing

The importer automatically accounts for the coordinate systems used by the input formats and performs the transformations required for GEM/MDL output. For FBX and OBJ files, normals are generated only if they are missing from the source model.

Polygon sidedness cannot be configured through JSON.

• For GLB/GLTF, the source material's doubleSided value is preserved.

• For FBX, the importer uses the material's two-sided setting and any CullingOff/CullingOn value explicitly assigned to the node.

• A submesh with no assigned material is forced to use twoSided=true.

Setting content.volumes=true does not generate volumes when none are present. This flag allows the importer to preserve and write volumes detected in the source model.

• When set to false, volume resources and .cmesh elements are removed before the output is written.

• Overwriting an existing .cmesh is controlled independently by overwriteExisting.cmesh.

The overwriteExisting flag

The overwriteExisting flags do not disable the export of new files. They protect only files that already exist. The following rules apply:

• if the file does not exist, it is written;

• if the file already exists, it is written only when overwriteExisting.<type> = true.

This parameter prevents existing, configured .def and .mdl files from being overwritten when the model is imported again.

Example settings for the overwriteExisting section

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

Texture processing

The searchPaths parameter specifies where the importer searches for source textures. It is also used to locate external images referenced by .gltf files.

The textureOutputSubdir parameter specifies the output subfolder for exported textures inside outDir.

The model is then written to <outDir>/<model_stem>/, and its textures are written to <outDir>/textures/<model_stem>/.

If textureOutputSubdir is empty, the textures are written next to the model.

Example settings for the textures section

"textures": 
    { 
    "searchPaths": ["D:/SourceTextures/Rock"], 
    "textureOutputSubdir": "textures", 
    "useTexturesFromModel": true, 
    "fileNameConvention": 
        { 
        "diffuse": ["basecolor", "base_color", "albedo", "diffuse"], 
        "lightmap": ["lm", "lightmap", "lightingmap"],
        "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"] 
        }
    }

The useTexturesFromModel parameter

1. Standard mode (default setting):

"useTexturesFromModel": true

The importer uses texture references from the source material: FBX material slots, OBJ .mtl, or glTF/GLB materials.

1. Alternative mode:

"useTexturesFromModel": false

The importer ignores texture references embedded in the model and searches for material folders next to the source model and directly inside each folder listed in searchPaths.

Without searchPaths:

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

To add an extra textures level, specify it explicitly relative to the model folder:

"searchPaths": ["textures"]

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

The same structure is used for an absolute searchPaths value:

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

Example for the matid_1 material:

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

Texture type suffixes are configured in import.textures.fileNameConvention:

"fileNameConvention": 
    { 
    "diffuse": ["basecolor", "base_color", "albedo", "diffuse"],
    "lightmap": ["lm", "lightmap", "lightingmap"], 
    "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"]
    }

The key is a field or slot in the generated .material. The key value is a list of accepted suffixes that follow the final underscore [ _ ] in the filename. The name of the immediate parent folder must match the material name. Files in folders belonging to other materials are ignored.

The importer compares only the part of the filename after the final underscore [ _ ]. Therefore, compound values containing underscores, such as base_color and normal_pbr, are not recognized. Use single-part values such as basecolor, normal, or normalmap.

When useTexturesFromModel=false, the names of exported .dds files and their references in .material are written in lowercase. This ensures exact path matching on case-sensitive file systems, including Linux.

Example of an incorrect parameter configuration

If the configuration file contains "bump": ["normal","normalmap","normal_pbr","bump","nm"],

the following files

matid_1/rock_normal.png

and

matid_1/rock_normalmap.png

will both be assigned to the bump field during import.

Command-line parameters

Command-line parameters allow you to change settings for a specific GEM Importer run. The supplied values take precedence over the corresponding values in gem_import.json but do not modify the configuration file.

Parameter	Description
No parameters	Create the gem_import.json configuration file with the basic import settings and exit on the first run. If gem_import.json already exists, import files according to the settings in the configuration file
-i, --input <file>	One input file. Supported formats: .fbx, .obj, .gltf, .glb, .mdl
--input-dir <dirs>	One or more input folders. Separate paths with a semicolon [ ; ]
--run-config	Import from import.general.inputDir
-s, --settings <file>	Use the specified gem_import.json
-o, --out-dir <dir>	Root output folder. Overrides import.general.outDir
--verbose [0 | 1 | 2 ]	Set the log file verbosity level
--html --no-html	Write an HTML log Write a TXT log
--dry-run	Read and validate only, without writing the regular output
--write-help	Write gem_import.md next to the executable
--version	Display the gem_import version and exit
-h, --help	Display command-line help

Running with a BAT file

For regular GEM Importer runs with the same parameters, you can create a BAT file. This eliminates the need to enter the command manually each time.

Create a text file in the folder containing gem_import.exe, add the launch command, and save the file with the .bat extension, for example, import_models.bat:

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

Double-click the BAT file to run the command. The pause command keeps the Command Prompt window open after the import is complete so that you can review the program messages.

Command-line examples

Enter all commands shown below in Windows Command Prompt.

1. Importing a single file:

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

The command imports vehicle.fbx, writes the output to D:\Out, and generates a detailed HTML log.

1. Importing files from multiple folders:

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

The command imports supported files from D:\Models\fbx and D:\Models\gltf. Folder paths are separated with a semicolon. The output is written to D:\Out, and the file log uses verbosity level 1.

1. Importing with a specified configuration file:

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

The command uses D:\Work\gem_import.json and imports files from the folders specified in import.general.inputDir.

Import output files

A typical import produces the following set of files:

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

The output file set depends on the source model and the data it contains.