TiMan: Add a practical, source-verified SOMA model-import workflow covering resources, mesh caches, Model Editor import, submesh reassignment, entity setup, testing, and troubleshooting.

2026-10-02T15:28:59Z

Add a practical, source-verified SOMA model-import workflow covering resources, mesh caches, Model Editor import, submesh reassignment, entity setup, testing, and troubleshooting.

New page

'''Importing a model''' brings exported mesh data into SOMA's resource pipeline. The route depends on the intended result:

* A fixed scene piece can be loaded as a '''static object''' from its model file.
* An interactive, animated, or physically configured object should be imported into <code>ModelEditor.exe</code> and saved as an '''entity''' (<code>.ent</code>).

SOMA ships primarily with Collada <code>.dae</code> source models and generated <code>.msh</code> mesh caches. The installed game also contains some <code>.fbx</code> files, especially under <code>entities</code>, but exporter-specific compatibility varies. Use the format supported by the documented exporter and verify the result in SOMA's tools.

== Prepare the files ==

# Export the model according to [[HPL3/SOMA/Modeling/Modeling Guidelines|Modeling Principles]] and the instructions for the chosen exporter.
# Put the model in its final mod resource directory, normally under <code>static_objects/</code> or <code>entities/</code>.
# Put its textures and <code>.mat</code> files in resource paths available to the mod.
# Confirm the directory is included by <code>resources.cfg</code> before opening the asset in an editor.

For automatic material resolution, assign the diffuse texture in the source model and provide an HPL3 material with the same base name. For example:

<pre>
panel.dae
panel.dds
panel.mat
</pre>

When the model references <code>panel.dds</code>, HPL3 looks for <code>panel.mat</code>. A model with multiple materials must use separate submeshes, each with its own texture/material reference.

== Validate the exported mesh ==

# Start <code>ModelViewer.exe</code> and load the exported model from its final resource location.
# Check that the object has the expected orientation, scale, pivot, submeshes, and materials.
# Inspect the tool output or HPL log for missing mesh, texture, or material messages.
# Close and reopen the asset after correcting the source export so stale state is not mistaken for a successful fix.

Loading a source mesh generates or refreshes its <code>.msh</code> cache. The executable contains an explicit “cache out of date” path that reloads the Collada source. Keep the source model in the mod; do not treat the generated cache as the editable master.

SOMA's shipped files demonstrate this pairing extensively: 5,444 inspected <code>.dae</code> files under <code>static_objects</code> and <code>entities</code> have a same-path <code>.msh</code> cache.

== Import the mesh into an entity ==

# Open <code>ModelEditor.exe</code> and choose '''File → New''' for a new entity.
# Choose '''File → Import Mesh''' and select the exported model.
# Confirm that the expected submeshes appear. Each imported mesh produces one or more submesh objects in the editor.
# Configure materials if a submesh did not resolve the intended <code>.mat</code> automatically.
# Add physics shapes and create bodies where the entity requires collision. Add joints, sub-entities, effects, or animations only as needed.
# Open '''Entity Settings''', choose the appropriate entity type, and configure its type variables.
# Save the entity as an <code>.ent</code> file in the same asset directory.
# Enable '''Entity Preview''' to inspect physics and animations before placing the entity in a map.

A representative shipped entity, <code>entities/urban/utility/air_vent/air_vent.ent</code>, stores this separation directly:

* its <code>Mesh</code> element references <code>air_vent.dae</code>;
* its imported <code>SubMesh</code> is stored under that mesh;
* its collision shape and body are separate sections; and
* its <code>UserDefinedVariables</code> select the <code>StaticProp</code> entity type.

The same directory also contains <code>air_vent.msh</code>. This illustrates the roles of the three files: <code>.dae</code> is the source mesh, <code>.msh</code> is the generated cache, and <code>.ent</code> is the entity setup.

== Reimport an updated mesh ==

When '''Import Mesh''' is used in an entity that already has a mesh, the Model Editor opens the '''SubMesh Reassign''' dialog. This allows saved submesh data to be associated with the new export.

* The left side lists new submeshes and lets each one be paired with an old submesh.
* '''Use new data''' discards the previous submesh parameters for that new submesh.
* The right side lists old submeshes that remain unassigned.
* '''Best Match''' attempts pairing based on triangle count according to the existing editor documentation.

Review every proposed match before accepting it. Stable submesh names and a stable object split make reimport safer; renamed, merged, or divided submeshes require deliberate reassignment. Save the <code>.ent</code> after accepting the mappings and test its bodies, attachments, and animations again.

== Use the result in a map ==

For a static object, select it through the Level Editor's '''Static Object''' mode. For an entity, select the saved <code>.ent</code> through '''Entity EditMode'''. Place one test instance, save and reopen the map, then launch the mod and verify:

* scale and orientation;
* material and texture loading;
* collision and player movement around the object;
* shadows and lighting;
* entity interaction or animation, where applicable.

== Troubleshooting ==

* '''The model cannot be found:''' confirm its folder is included by <code>resources.cfg</code> and that the editor is working on the intended mod.
* '''The model is invisible or malformed:''' verify export scale, up axis, transforms, normals, and triangulation in the source application, then regenerate the cache.
* '''The material is missing:''' confirm that each submesh has a diffuse texture reference and that the corresponding same-base-name <code>.mat</code> can be resolved.
* '''The wrong material appears:''' check for duplicate asset names elsewhere in the resource paths and inspect the submesh's assigned material in Model Editor.
* '''An entity breaks after reimport:''' revisit SubMesh Reassign. A changed skeleton can also make the saved <code>.ent</code> incompatible with the new mesh; SOMA reports this condition as an out-of-date entity/mesh skeleton.
* '''The editor still shows the old model:''' close and reopen the entity or editor after replacing the source and cache; do not assume an in-place resource refresh succeeded.

== See also ==

* [[HPL3/SOMA/Modeling/Modeling Guidelines|Modeling Principles]]
* [[HPL3/SOMA/Modeling/Exporting Models|Exporting Models]]
* [[HPL3/Entities/Model Editor View|Model Editor reference]]
* [[HPL3/Entities/Entity Mesh|Submeshes and reassignment]]
* [[HPL3/Entities/Entities Overview|Entity workflow]]

[[Category:English]]

HPL3/SOMA/Modeling/Importing Models - Revision history

TiMan: Add a practical, source-verified SOMA model-import workflow covering resources, mesh caches, Model Editor import, submesh reassignment, entity setup, testing, and troubleshooting.