HPL3/SOMA/Modeling/Modeling Guidelines

Modeling principles are the preparation rules that make a 3D asset predictable when it is exported, loaded, textured, and given collision in SOMA. They apply before the asset is configured as a static object or an entity.

Plan the asset's role

Decide how the model will be used before splitting the mesh or building collision:

• A static object is map geometry intended to remain fixed. Nearby static objects with matching material and render settings can be combined by the engine, so reusable architectural pieces benefit from shared materials.
• An entity is saved as an .ent file and can contain a mesh, physics shapes and bodies, joints, sub-entities, effects, and animations. Its behavior is selected through an entity type.
• A detailed visible mesh and a practical collision shape need not be identical. Complex or rounded visible geometry often benefits from simpler physics shapes configured in the Model Editor.

Use a static object for fixed scenery unless the object needs entity features such as scripted behavior, articulated physics, animation, or per-instance gameplay variables.

Scale, axes, and origin

• Work at a consistent real-world scale. The SOMA export guide recommends treating one unit as one metre, or using centimetres consistently so a one-metre object is 100 units high. Exported unit metadata may be used by the importer.
• Keep the same unit scale for a rigged mesh and all of its animations. The documented result of a mismatch is an animated mesh that expands or shrinks.
• Configure the source application's up axis deliberately and validate the export in SOMA. Of 5,490 inspected shipped Collada files, 5,207 declare Y_UP and 283 declare Z_UP; the installed assets therefore do not justify treating one declaration as universal.
• Place the origin deliberately. The existing SOMA modeling guide recommends positioning an ordinary prop so its bottom is at the origin. This gives a useful placement point on floors; doors, wheels, and other pivoting objects instead need an origin suited to their intended movement.
• Apply or otherwise account for object transforms before export according to the exporter being used. Validate the result in an HPL3 tool rather than assuming the modeling application's displayed scale is authoritative.

Geometry and submeshes

• Give exported objects and mesh datablocks stable, descriptive names. Submesh names matter when an existing entity is reimported and its saved submesh data must be reassigned.
• Export polygon meshes in a form the selected exporter can reliably convert. The shipped Collada example inspected for this guide records triangle export, and the existing Modo and Blender guidance requires triangulation before export.
• Remove accidental duplicate geometry and unused objects from the export selection.
• Split geometry by material where necessary. HPL3 assigns one material to each submesh; a model needing multiple materials therefore needs multiple submeshes.
• Avoid unnecessary submesh and material splits. For static geometry, nearby objects that share a material and compatible settings can be combined at load time, reducing draw calls.
• Keep collision requirements in mind while modeling. Render geometry that is too detailed for collision can use simpler shapes or a separate collision setup in an .ent file.

UVs and materials

• UV-unwrap every textured submesh and keep the UV layout valid for the texture workflow being used.
• Assign the intended diffuse texture to every exported submesh. The importer uses that texture reference to locate the corresponding HPL3 .mat file.
• Match the diffuse texture and material base names. For example, a submesh using panel.dds should have a material named panel.mat available through the resource paths.
• Use distinct texture/material base names for distinct submesh materials, such as door_frame.dds/door_frame.mat and door_leaf.dds/door_leaf.mat.
• Set each material's physics material deliberately when its surface will provide collision. One .mat file has one physics-material setting.

The older SOMA project guide gives historical recommendations for texture formats, suffixes, and relative sizes. Treat those as project conventions, not as proof that every modern mod asset must use the same compression or dimensions. The material file and the current tool output are the authoritative test.

Organize files predictably

Keep an asset's source model, generated cache, materials, textures, and optional entity file in a stable resource directory. A typical entity asset may look like:

entities/my_mod/machine/
├── machine.dae
├── machine.msh
├── machine.ent
├── machine.dds
├── machine_nrm.dds
└── machine.mat

The exact texture set depends on the material. Same-basename organization is not an engine requirement for every auxiliary texture, but it makes dependencies easier to identify and matches many shipped SOMA assets. In the installed game, 2,944 entity assets have same-basename .ent, .dae, and .msh files.

Make sure the containing directory is included by the mod's resources.cfg. Do not rely on absolute paths embedded by the modeling application; test the asset from its final mod-relative location.

Validate in small steps

1. Export the source mesh into its final resource directory.
2. Load it in ModelViewer.exe or import it into ModelEditor.exe.
3. Check orientation, dimensions, origin, normals, UVs, and material assignment before adding gameplay setup.
4. If it will be an entity, save a minimal .ent, then add shapes, bodies, joints, and type variables incrementally.
5. Place the static object or entity in a test map and check it in-game under representative lighting.
6. Re-export once and verify that the update workflow preserves the intended submesh assignments.

This staged process separates mesh/export problems from material, physics, entity-type, and map-placement problems.

Common problems

• Wrong size: verify the source scene units and exported unit metadata. For animated assets, verify the mesh and animation use the same scale.
• Wrong orientation or pivot: fix the source axes/origin and re-export rather than compensating separately in every map instance.
• Missing material: confirm that the submesh has a diffuse texture reference and that the matching .mat is reachable through the mod resources.
• Only one material appears: separate faces that need different materials into different exported submeshes.
• Collision is expensive or catches on details: use simpler Model Editor shapes or a deliberately simplified collider instead of the full visible mesh.
• Reimport loses setup: keep stable submesh names and review every mapping in the SubMesh Reassign dialog.

See also

• Importing Models
• Exporting Models
• Working with Materials
• Entities Overview
• Blender HPL3 export plugin