HPL3/SOMA/Modeling/Importing Models

From Frictional Wiki
< HPL3‎ | SOMA‎ | Modeling
Jump to navigation Jump to search

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 ModelEditor.exe and saved as an entity (.ent).

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

Prepare the files

  1. Export the model according to Modeling Principles and the instructions for the chosen exporter.
  2. Put the model in its final mod resource directory, normally under static_objects/ or entities/.
  3. Put its textures and .mat files in resource paths available to the mod.
  4. Confirm the directory is included by resources.cfg 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: 

panel.dae
panel.dds
panel.mat

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

Validate the exported mesh

  1. Start ModelViewer.exe and load the exported model from its final resource location.
  2. Check that the object has the expected orientation, scale, pivot, submeshes, and materials.
  3. Inspect the tool output or HPL log for missing mesh, texture, or material messages.
  4. 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 .msh 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 .dae files under static_objects and entities have a same-path .msh cache.

Import the mesh into an entity

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

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

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

The same directory also contains air_vent.msh. This illustrates the roles of the three files: .dae is the source mesh, .msh is the generated cache, and .ent 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 .ent 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 .ent 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 resources.cfg 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 .mat 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 .ent 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

Retrieved from "https://wiki.frictionalgames.com/page?title=HPL3/SOMA/Modeling/Importing_Models&oldid=7320"