HPL3/SOMA/Modeling/Exporting Animations

Exporting an animation creates a source clip that SOMA can register on an entity. SOMA's shipped entities use .dae_anim and .fbx animation sources; the engine generates .anm cache files from supported sources.

This guide describes requirements visible in SOMA's shipped files and executables. Exact menu names and exporter options depend on the 3D application and exporter version.

Start from the entity mesh

Use the same production rig or animated node hierarchy used to export the entity mesh.

• Keep node and bone names stable. Exported animation channels target names such as joint1/matrix or ball/translate.Y.
• Keep hierarchy changes deliberate. SOMA reports a mismatch when the skeleton in the mesh differs from the skeleton saved in the entity.
• Keep the mesh and clips on a consistent scale convention. The installed .dae_anim files carry unit metadata with several labels and factors, so the label alone is not a reliable project rule; verify the resulting movement against the imported mesh.
• Use an axis configuration known to work for that asset pipeline. Of 876 installed .dae_anim files, 869 declare Y_UP and seven declare Z_UP.
• Ensure every skinned vertex has a valid bone assignment and no more than four bone influences. SOMA contains explicit diagnostics for both failures.

Prepare one clip per action

Export separate source files for independently selectable actions such as idle, open, close, or a transition between two poses.

Before export:

1. Set the intended start and end of the clip.
2. Remove unrelated animation takes or actions from the export selection.
3. Include the bones or animated nodes needed by the entity.
4. Preserve the bind/rest relationship expected by the mesh.
5. Decide whether the clip should loop. For a loop, compare the first and last poses and remove an unintended visible jump.
6. Export to the final mod-relative animation directory.

Do not bake sounds, particles, or gameplay callbacks into assumptions about the source format. SOMA stores those as events in the entity's animation registration.

Choose a source format

Collada animation source

SOMA ships 876 .dae_anim files. Each is a Collada XML document and every inspected file contains at least one animation channel. The sources contain between 1 and 487 channels, targeting matrices, visibility, rotation, translation, and scale.

The extension distinguishes an animation source from a normal .dae mesh file, but shipped .dae_anim files can still contain geometry, materials, controllers, and scene data in addition to animation channels.

Seventy-one shipped .dae_anim files retain explicit OpenCOLLADA export-option comments. All 71 record animation and joint/skin export as enabled. They do not use one universal sampling setting: 15 record sampling enabled and 56 disabled. Likewise, static-curve removal varies. These values show that one copied exporter preset is not valid for every shipped clip.

FBX animation source

SOMA entities contain 110 registrations referencing .fbx animation files. This proves that the shipped pipeline uses FBX clips, but not that every modern FBX version or exporter setting is compatible with SOMA's older importer. Test a minimal clip before committing to a production pipeline.

Generate and inspect the cache

Place the source file in its final resource directory, then load it through the Model Editor or an entity that references it. SOMA uses same-stem .anm files as compiled animation data.

Examples from the installed game include:

shower_curtain_open.fbx  → shower_curtain_open.anm
ventilation_cluster_spin.dae_anim → ventilation_cluster_spin.anm

Do not hand-edit the binary .anm. Re-export the source and let the engine/tool pipeline refresh generated data. SOMA reports when an animation source cannot be found or compiled.

First-success export test

1. Export a short clip that moves one clearly identifiable bone or node.
2. Put it beside the target entity or in that entity's animation subdirectory.
3. Add it to the entity with a unique name, Speed=1, and no events or transitions.
4. Preview the clip and enable skeleton display.
5. Confirm the expected node moves, the mesh keeps its scale, and the start/end frames are correct.
6. Save and reopen the entity, then play the registered name in a test map.
7. Only after this succeeds, export the remaining clips and add events or transitions.

The shipped ventilation_cluster_spin.dae_anim is a useful structural example: it declares ten channels targeting root and eight joint matrices plus root visibility, and its entity registers the clip on the Default layer with a speed of 1.2.

Troubleshooting

• The clip cannot be found: verify the exported file path, extension, filename case, and resources.cfg coverage.
• Nothing moves: confirm the source contains animation channels and that their target names exist in the entity mesh hierarchy.
• The mesh scales or offsets unexpectedly: compare mesh and animation unit metadata, axis settings, root transforms, and bind/rest setup.
• Only part of a skinned mesh follows: check for unweighted vertices and excessive bone influences; SOMA explicitly diagnoses both.
• The entity reports a skeleton mismatch: reimport the mesh into the entity and export the animation from the matching hierarchy.
• A loop jumps: inspect the first and last poses and the intended playback range in the source application.
• Old motion persists after export: reload the entity and refresh the generated .anm cache.

See also

• Animation Overview
• Importing Animations
• Exporting Models
• Blender HPL3 export plugin