SUBMODEL MERGING

IMPORTANT! This feature is a BETA feature and as such you may encounter bugs/issues, which should be reported.

 

Submodel merging is a way to facilitate the re-use of 3D models across multiple game assets. The technique reduces download sizes, saves space on disk, and reduces memory usage in the simulation. This feature was initially developed with the intent of being able to more easily create mesh liveries for airplanes without having to re-export the entire airplane, however it has multiple uses throughout the creation of different assets, for example:

  • Airport personnel with different kinds of clothing.
  • Cars or boats that have a base model but requires variations like being convertible or having a spoiler.
  • Aircraft model variations, like having a base aircraft and then slightly different models for purposes like rescue or military.

 

What submodel merging does is merge partially exported hierarchies based on unique identifiers that exist on the nodes in the model's node hierarchy. In this way, the relevant parts of the mesh hierarchy can be exported and merged at runtime with the base model, instead of having to export multiple full models with very minor differences.

NOTE: This functionality is currently not supported when using The Blender Plugin.

It is also worth noting that the code put in place to deal with submodels is also applicable when working with animations, and has deprecated the <AnimationFileList> element from the [model].xml file. This has been replaced by the <MergeModel> element, and you can see an example of it's use for both submodels and animations here: Submodels And Animations.

NOTE: As a replacement for the <AnimationFileList> functionality, sub-models are more efficient, since the submodel data is shared across all models that use it, whereas the <AnimationFileList> code duplicated the animation data.

Note that this is not the same as the Model Attachments feature, since the glTF files used for sub-model merging should maintain the hierarchy and LOD levels of the original "main" model, while attached models can have a distinct hierarchy and will have the LOD limits applied to them independently.

 

 

Restrictions

Please note the following restrictions when working with sub-models:

  • All submodels that are to be merged into the main model, must be part of the same project in the Project Editor.
  • You cannot merge models or animations from other projects.
  • Gauge rendering is not covered currently.
  • Attaching a whole SimObject is not available.
  • Inputs are not supported yet in the attached ModelInfo.

 

Essentially, sub-models can only be used to attach a relatively simple model with animations and a small amount of behavior logic in it.

 

 

Exporting Submodels

When exporting your submodels from 3DS Max using the Babylon Utilities exporter, you need to do the following:

  • Select all nodes to be exported as a submodel
  • Enable the "Export selection as submodel" toggle in the Babylon Exporter
  • Make sure the "ASOBO_uniqueID" is enabled (for both the base model and the submodel exports)

The Babylon Exporter Submodel Export Settings

 

Note that if there are any nodes with the same unique ID value, then you will get warning about the conflict. Node IDs are - by default - based on the name of the object and so if you have multiple objects with the same name in your scene, the node IDs will also be the same. To resolve these issues, you can set the unique node ID manually using the Object Properties, where you can find the Unique Node ID parameter and change it.

Conflicting Node ID Error In The Multiexporter

Alternatively, you can use the option Babylon Resolve UniqueIDs from the Babylon menu to try and resolve the issues automatically:

The Babylon Tool To Resolve Unique ID Conflicts

 

Creating Submodels

Here we give a series of tips and recommendations for artists creating models that want to benefit from submodel merging:

 

  • Merging happens by unique id, not by node name.
    • This unique id is visible in the Babylon Object Properties.
    • The default unique id for a new node is its name, which is fixed on the first export (but can later be changed by hand).
    • This means base model node names can be changed without having to re-export all submodels (though this is not recommended).
  • Do not export animations for a given node in more than one merged model (base model and submodels). See section 2.b in the The Merge Process section for more information.
  • Do not export meshes in more than one merged model. See section 1.d in the The Merge Process section for more information.
  • Try to avoid re-organizing (i.e. changing parents of nodes in) the part of the hierarchy that is shared between (sub)models.
    • Shared nodes between (sub)models are:
      • Nodes selected for export
      • Parents of nodes selected for export
      • Nodes targeted by exported animations
      • The hierarchy defined by nodes used as joints in exported skinned meshes, up to the last common ancestor (the implicit "root" of the skeleton)
    • Only objects (meshes, cameras, …) on nodes selected for export are exported. Objects on the other nodes are not exported.
    • This means you can change the grand-parent of a node that is exported, but not the direct parent of the exported node.
    • If you do need to change the hierarchy, make sure to export all submodels that use this part of the hierarchy (gltf merging will fail if the merge is invalid).
  • Try to avoid renaming nodes. See section 1.c.i in the The Merge Process section for more information.
  • Try to avoid duplicate node names in the merged models, if they are not actually the same node.
    • Only important if used for gameplay/model behavior purposes, because you won't know which node you will get.
  • Try to avoid materials with the same name in more than one merged models, if they do not represent the same material (e.g. they have different textures or other material settings).
    • Only important for gameplay/model behavior purposes, which sometimes looks for materials by name and replaces them with another (which may result in one of the merged models changing material settings/textures).
  • If your submodel has any skinned meshes, then the export must also include the bones. Submodels with skins that have bones in the base model or another submodel will not export correctly. Alsao make sure that you do not have more than one root in the skinned bones list, otherwise, you'll get an error: "More than one root node for the skin."
  • In the cases where your submodels have a skin, you need to make sure there is at least one common ancestor between the submodel mesh and the skin bones.

 

 

The Merge Process

What follows is a detailed description of the merging process, where the destination model is the final result of the merge, and the source model is a model that is merged into the destination model.

 

  1. Node hierarchies are merged as follows:
    For every node in the source model, look it up in the destination model.
    1. If it does not exist yet, it is created.
      1. The node gets its translation/rotation/scale at this point. If later submodels have the same node, their transform is ignored.
      2. Look up the parent in the destination model, using the source model node's parent unique id.
        1) If found, add the created node as a child of said parent.
        2) If not found, there is an error, merging is aborted.
    2. If it does exist, verify that the node's parent ids are identical in the source and destination model.
      1. If not identical, there is an error, merging is aborted.
    3. Check if the destination and source node names are identical.
      1. If not, there is a warning. The first-encountered node name is kept in the destination model.
    4. Check which of the models [destination, source] have an object on this node (mesh, camera, …).
      1. If both have an object, there is an error, merging is aborted.
      2. If only the destination has an object, continue.
      3. If only the source has an object, clone it into the destination node.
      4. If neither has an object, continue.
  2. Animations are merged as follows:
    For every animation with a given name in the source model, check if it exists with that name in the destination model.
    1. If it does not exist yet, copy the animation.
    2. If it exists, it is merged with the source model's animation. If the target already exists in the source model, the animation will be ignored. In the future, this will produce an error.
  3. Materials are not merged.
    This means that if materials have the same name in two separate source models, they will have the same name in the resulting destination model. If this material name is used in model behavior logic, or elsewhere, know that you may find materials with the same name originating from different (merged) models.