Runtime Model Import

Simulation Development Workflow → Importing 3D Models

Up to date for Platform 0.40.2

Written by Connor Jakubik and Alex Sein

Prerequisites:

• https://github.com/SimDynamX/SpaceTeamsPro/wiki/Entity-Types

---

Importing 3D Models

Space Teams provides a 3D Model and Texture import functionality to allow users to use their own CAD and graphics work in their sims. The entity type Object_Loaded is used to create an entity with an imported mesh as its body. As of v0.28.0, only the GLTF format is supported (both .glb and .gltf).

NOTE: The previous method of model import was the Entity_Loaded_BP BP-type entity. Object_Loaded is an improved replacement that takes in the same models, with somewhat different parameter layout.

Core library of materials

Name
M_Metal_Aluminum
M_Metal_Aluminum_Brushed
M_Metal_Aluminum_Coated
M_Metal_Dark
M_PlasticWhite
M_PlasticGray
M_PlasticBlue
M_Metal_Black
M_Light
M_Foil_Gold
M_Metal_Brown
M_Metal_Brass
M_Radiator
M_Solar_Panel
M_Metal_Green
M_Metal_Red
M_Glass

Blender Material Slot Setup

This is discussed in greater detail in the Materials section. In general, material slots can have any name that is also a valid Space Teams PRO parameter name. Note that Space Teams PRO is more restrictive about parameter names than Blender—the only valid special characters for parameters are the hash and the underscore. If the material slot has the same name as one of the "Core" tiling materials listed above, that material slot will be assigned the corresponding tiling material on import. Any custom materials must not share their names with any materials on that list.

An example is provided below. The Space Teams material setup for this mesh is also shown in the Materials section.

Blender Export Settings

1. When you are ready to export your model, go to File > Export and select glTF 2.0 (.glb/.gltf). If you only want certain objects to be exported, select them before doing this.

2. The recommended export settings are:

WARNING: As of v0.30.0, the rotation of imported meshes seems to act like this:

• +Y Up true: Mesh is rotated 90 degrees around X axis compared to expected pose based on Blender view.
• +Y Up false: Mesh is rotated 180 degrees around X axis compared to expected pose based on Blender view. From this, you can use the RotateX parameter to add an additional rotation to the mesh to compensate. Further testing, fixes, and documentation will be done soon.

3. It's recommended to limit the export to visible objects (second checkbox under Include). This ensures no unwanted invisible objects accidentally get exported.
4. Under Data > Material ensure that the Materials dropdown is set to Export—not doing this will result in your model not having the right material slots, and consequently being rendered as a blank material.

---

Object_Loaded Entity type parameters

In the Entity with "Type": "Object_Loaded", the #Object_Loaded param map holds the parameters that are used to import the mesh.

#Object_Loaded Required Parameters:

• Mesh_Path: a string with the filepath to the GLTF-formatted file to load. .gltf and .glb are supported.
  • Core assets: Core/...path to the file in ST install directory.
    • Example: Core/SharedData/SCAssets/LoadableMeshes/SpaceX_Starship/SpaceX_Starship.gltf
  • Local assets: Local/...path to the file inside Local Assets folder
    • Example: Local/Repos/MySpaceshipStuff/Soyuz1.glb
• Scale3D: a doubleV3 of x,y,z axis scale which is applied to the mesh

Optional parameters

• RotateX: a bool, which if present and true, rotates the mesh by 180 degrees on the entity X axis.

Materials

• If the GLTF has any mesh sections with materials assigned to them that do not match with our Core Library of materials, the Materials param map in the #Object_Loaded map is checked for a user-configured material.
• The name of the material, which would match with the material assignment on a mesh section, is the param map name inside Materials.
• Inside each Material map, there are several possible inputs for material information. These inputs are described in further detail below; note that not all inputs are required in order to create a valid material.
  • Each input's Source parameter can contain either a double, doubleV3, or string value.
    • If a double value exists, it is used as a 0 to 1 fraction of black to white; this value is applied equally to every channel of the input.
    • If a doubleV3 value exists, its x, y, and z values are passed directly to the Red, Green, and Blue channels as 0 to 1 fractions. The Alpha channel, if it exists, is assumed to be 1 (fully opaque).
    • If a string value exists, the string is used as a filepath to load an image as a Texture for the material.
      • Valid file types: jpg, png, some others.

        • NEEDS VALIDATION

      • Must be 8 bits per channel. The 8-bit 0-255 scale maps to 0 to 1 for the channel value.

        • NEEDS VALIDATION

      • Best performance if image resolution is a power-of-2 size square.
      • Filepath rules:
        • Core assets: Core/...path to the file in ST install directory.
          • Example: Core/SharedData/SCAssets/LoadableMeshes/Gateway/International_Habitation_Module_metallic.jpg
        • Local assets: Local/...path to the file inside Local Assets folder
          • Example: Local/Repos/MySpaceshipStuff/Soyuz1.png
  • Each input's Channels parameter describes which of the Source's channels (Red, Green, Blue, Alpha, or RGBA) will actually be used for this input. For example, some textures package single-channel metallic and roughness maps into the same texture. The metallic map might be the Blue channel, while the roughness map might be the Green channel. In that case, the same texture file would be used as the source for both the Metallic and Roughness inputs, but with different channels specified for each.
    • Valid "channels" for the Channels parameter are:
      • RGB: default if the Channels parameter is missing. Uses Red, Green, and Blue channels and defaults Alpha to 1, if applicable.
      • R, G, B, or A individually: uses that channel in the same way as a double for the Source parameter would (see above).
      • RGBA: explicitly uses all channels, including the Alpha (transparency) channel.
  • Each input's UV_Scale parameter describes how much to scale the tiling of the material. The higher the number, the more detailed the texture will appear. However, patterns in the texture will begin to repeat and will become noticeable at higher and higher UV_Scales.
    • UV_Scale is a 2D vector, or doubleV2. The first (x) value is the U-direction scale, and the second (y) is the V-direction scale. On a texture image, these represent the horizontal and vertical directions, respectively.
    • Most textures do not require any additional UV scaling. Use this parameter only if you know your texture is seamless, and thus can be tiled.
    • Universal Digital Image Tiles (UDIMs) are not guaranteed to work at the moment, but will be supported in the future.
    • This parameter is only applicable to texture-based (string) Sources, and has no effect on double or doubleV3 Sources.
• List of material inputs:
  • Albedo
    • Base color of the material
    • Required (will log an error if missing)
    • Default: Magenta (1.0, 0.0, 1.0)
  • Metallic
    • How metal-like the material is
      • 0.0 represents a non-metal (plastic, rock, sand, etc.)
      • 1.0 represents a metal (copper, aluminum, etc.)
      • Values between 0.0 and 1.0 are not recommended, as they rarely represent physical materials. For "metallic paint" materials, either a "clear coat" or a layered material implementation is necessary; however, neither is currently supported.
    • Default: 0.0
  • Roughness
    • How rough the surface is at a small scale. 0 is mirror-like. 1 is completely diffuse. Most materials fall somewhere between these extremes.
    • Default: 0.5
  • Normal
    • Surface-relative vector defining per-pixel surface normal vector, to be used for shading
      • No deviation from the geometry normal vector: 0.0, 0.0, 1.0, or blue. This is in what's known as "Tangent Space"
    • Space Teams PRO uses the "DirectX" convention for normal maps (the other option is "OpenGL," which will result in a flipped y-direction for all normals)
    • Default: Use geometry normal vector (0.0, 0.0, 1.0)
  • Emissive
    • Emitted light from the surface in Red, Green, and Blue channels
    • 1 is 1 nit, possible to go far above 1.
    • NOTE: The light from emissive surfaces doesn't light the scene as effectively as the "real" light sources in the scene (sunlight, point and spotlights that are added in the sim, etc.)
    • Default: Zero light emitted (0.0, 0.0, 0.0)

An example using the Gateway iHAB module is shown below. This mesh had two materials on it, and the whole model had four materials. For clarity, only one material is shown—the others were set up in a similar way, only with different paths to the appropriate texture files.

"#Object_Loaded": {
  "Scale3D": [ "doubleV3", 100.0, 100.0, 100.0 ],
  "Mesh_Path": "SharedData/SCAssets/LoadableMeshes/GatewayNew/Models/iHAB.glb",
  "Materials": {
    "iHab_main": {
      "Albedo": {
        "Source": "Core/SharedData/SCAssets/LoadableMeshes/GatewayNew/Textures/iHAB_main_BaseColor.png-iHAB_main_Alpha.png",
        "Channels": "RGBA",
        "UV_Scale": [ "doubleV2", 1.0, 1.0 ]
      },
      "Metallic": {
        "Source": "Core/SharedData/SCAssets/LoadableMeshes/GatewayNew/Textures/iHAB_main_Metallic.png-iHAB_main_Roughness.png",
        "Channels": "B"
      },
      "Roughness": {
        "Source": "Core/SharedData/SCAssets/LoadableMeshes/GatewayNew/Textures/iHAB_main_Metallic.png-iHAB_main_Roughness.png",
        "Channels": "G"
      },
      "Normal": {
        "Source": "Core/SharedData/SCAssets/LoadableMeshes/GatewayNew/Textures/iHAB_main_Normal.png",
        "Channels": "RGB"
      }
    },
  }
},

Schema 3.0 Material Configuration

As of Space Teams PRO version 0.40.2, there is a new material configuration schema (3.0) that addresses key issues in the previous version (2.0). The previous section covers schema 2.0, while this section shows the changes to that schema and describes their impact on the model import workflow. For a direct comparison, the Gateway iHAB example is replicated below in schema 3.0:

"#Object_Loaded": {
  "Scale3D": [ "doubleV3", 100.0, 100.0, 100.0 ],
  "Mesh_Path": "SharedData/SCAssets/LoadableMeshes/GatewayNew/Models/iHAB.glb",
  "Materials": {
    "PutAnyValidParameterKeyHere": {
      "Name": "iHab_main",
      "Albedo": {
        "Source": "Core/SharedData/SCAssets/LoadableMeshes/GatewayNew/Textures/iHAB_main_BaseColor.png-iHAB_main_Alpha.png",
        "Channels": "RGBA",
        "UV_Scale": [ "doubleV2", 1.0, 1.0 ],
        "UV_Offset": [ "doubleV2", 0.0, 0.0 ]
      },
      "Metallic": {
        "Source": "Core/SharedData/SCAssets/LoadableMeshes/GatewayNew/Textures/iHAB_main_Metallic.png-iHAB_main_Roughness.png",
        "Channels": "B"
      },
      "Roughness": {
        "Source": "Core/SharedData/SCAssets/LoadableMeshes/GatewayNew/Textures/iHAB_main_Metallic.png-iHAB_main_Roughness.png",
        "Channels": "G"
      },
      "Normal": {
        "Source": "Core/SharedData/SCAssets/LoadableMeshes/GatewayNew/Textures/iHAB_main_Normal.png",
        "Channels": "RGB"
      }
    },
  }
},

The most critical change is that material parameter names no longer have to match the material slot names on the 3D model. Instead, the slot names are linked through the Name parameter. This means that it is no longer required to have material names that match the STP parameter naming scheme (where special characters other than _ and # are not allowed).

The UV_Offset parameter is another new addition, and will allow for the translation of textures relative to the 3D model's UV coordinates. However, this is not implemented as of 0.40.2.