TiMan: Add a SOMA-file-verified animation export guide covering hierarchy compatibility, source formats, cache generation, first-success testing, and troubleshooting.

2026-10-02T17:16:50Z

Add a SOMA-file-verified animation export guide covering hierarchy compatibility, source formats, cache generation, first-success testing, and troubleshooting.

New page

'''Exporting an animation''' creates a source clip that SOMA can register on an entity. SOMA's shipped entities use <code>.dae_anim</code> and <code>.fbx</code> animation sources; the engine generates <code>.anm</code> 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 <code>joint1/matrix</code> or <code>ball/translate.Y</code>.
* 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 <code>.dae_anim</code> 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 <code>.dae_anim</code> files, 869 declare <code>Y_UP</code> and seven declare <code>Z_UP</code>.
* 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 <code>idle</code>, <code>open</code>, <code>close</code>, or a transition between two poses.

Before export:

# Set the intended start and end of the clip.
# Remove unrelated animation takes or actions from the export selection.
# Include the bones or animated nodes needed by the entity.
# Preserve the bind/rest relationship expected by the mesh.
# Decide whether the clip should loop. For a loop, compare the first and last poses and remove an unintended visible jump.
# 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 <code>.dae_anim</code> 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 <code>.dae</code> mesh file, but shipped <code>.dae_anim</code> files can still contain geometry, materials, controllers, and scene data in addition to animation channels.

Seventy-one shipped <code>.dae_anim</code> 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 <code>.fbx</code> 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 <code>.anm</code> files as compiled animation data.

Examples from the installed game include:

<pre>
shower_curtain_open.fbx → shower_curtain_open.anm
ventilation_cluster_spin.dae_anim → ventilation_cluster_spin.anm
</pre>

Do not hand-edit the binary <code>.anm</code>. 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 ==

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

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

== Troubleshooting ==

* '''The clip cannot be found:''' verify the exported file path, extension, filename case, and <code>resources.cfg</code> 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 <code>.anm</code> cache.

== See also ==

* [[HPL3/SOMA/Animation/Animation Overview|Animation Overview]]
* [[HPL3/SOMA/Modeling/Importing Animations|Importing Animations]]
* [[HPL3/SOMA/Modeling/Exporting Models|Exporting Models]]
* [[HPL3/Blender HPL3 export plugin|Blender HPL3 export plugin]]

[[Category:English]]

HPL3/SOMA/Modeling/Exporting Animations - Revision history

TiMan: Add a SOMA-file-verified animation export guide covering hierarchy compatibility, source formats, cache generation, first-success testing, and troubleshooting.