TiMan: Add a SOMA-file-verified animation import guide covering entity registration, caches, preview, events, transitions, script testing, and troubleshooting.

2026-10-02T17:16:49Z

Add a SOMA-file-verified animation import guide covering entity registration, caches, preview, events, transitions, script testing, and troubleshooting.

New page

'''Importing an animation''' registers an exported animation source on a SOMA entity so the clip can be previewed and played by name.

== Before importing ==

Confirm that:

* the entity already loads its intended animated mesh;
* the exported animation uses the mesh's node or bone names;
* the animation and mesh were exported with compatible scale and axis settings;
* the animation file is in a directory included by the mod's <code>resources.cfg</code>; and
* the source file has a unique, stable path inside the mod.

SOMA ships entity registrations that reference both <code>.dae_anim</code> and <code>.fbx</code> sources. This establishes support for those installed assets, not compatibility with every exporter version. Verify the chosen exporter with a minimal clip before producing a full animation set.

== Add a clip to an entity ==

# Open the target <code>.ent</code> file in <code>ModelEditor.exe</code>.
# Enable '''Entity Preview''' from the lower toolbar.
# Open '''Edit Animations''' in the preview window.
# Choose '''Add new animation'''.
# Set a unique '''Name''' used by scripts and entity logic.
# Set '''File''' to the exported <code>.dae_anim</code> or <code>.fbx</code> source.
# Use <code>Default</code> for '''Layer''' unless the entity has a known layered setup.
# Begin with '''Speed''' set to <code>1</code>.
# Save the entity and select the new animation in the preview controls.

The saved entity entry has this basic form:

<syntaxhighlight lang="xml">
<Animations>
<Animation
Name="open"
File="entities/urban/toilet/shower_curtain/shower_curtain_open.fbx"
Layer="Default"
Speed="1"
/>
</Animations>
</syntaxhighlight>

This example is taken from SOMA's shipped <code>shower_curtain.ent</code>. The animation's registered name is <code>open</code>; scripts play that name, not the filename.

== Understand source and cache files ==

SOMA stores compiled animation data in <code>.anm</code> files. After deduplicating the paths referenced by shipped entity animation registrations:

* 939 non-empty source paths are registered;
* 879 corresponding source files are present in the installation;
* 866 of those present sources have a same-stem <code>.anm</code> file;
* 785 of those pairs use <code>.dae_anim</code> sources; and
* 81 use <code>.fbx</code> sources.

For example:

<pre>
ventilation_cluster_spin.dae_anim
ventilation_cluster_spin.anm
</pre>

The source is the file registered on the entity. Treat <code>.anm</code> as generated engine data. When replacing a source animation, reload the entity and verify that the cache was refreshed rather than editing the cache manually.

== Preview and validate ==

Use Entity Preview to check:

* whether the animation appears in the selector;
* whether it plays at the expected speed;
* whether looping behaves correctly;
* whether the skeleton moves without unexpected scaling or offsets;
* whether the first and last poses meet correctly for a loop; and
* whether physical bodies, sockets, and attached effects remain aligned.

The preview window can display the skeleton and physical objects and provides play, loop, step, time, and timeline controls.

SOMA's executable reports useful failures, including missing animation files, skeleton differences between the mesh and saved entity, vertices without a bone, vertices influenced by more than four bones, and missing transition animations.

== Add events ==

Events are added to the registered animation in the Model Editor, not baked into the exported source file. Each shipped event record stores a name, time, type, destination socket, and value.

Available event types declared by SOMA include:

* <code>PlaySound</code>
* <code>CreateParticle</code>
* <code>Step</code>
* <code>Message</code>
* <code>PlayLoopSound</code>
* <code>StopLoopSound</code>

Add an event at the intended timeline position, choose its type, and provide the resource or socket required by that type. Test it in preview and in-game. A valid animation can still have a failing event if its sound, particle system, or destination socket is missing.

SOMA's <code>robot_arm_welding.ent</code> demonstrates timed loop sounds, ordinary sounds, particles attached to sockets, and a stop-loop event on one animation.

== Add transitions ==

A transition registers a separate bridge clip to use when entering the selected animation from a previous animation.

# Register the base, target, and bridge clips as ordinary animations first.
# Confirm that each clip plays independently.
# Add a transition to the target animation.
# Set the previous animation and the bridge-animation name.
# Adjust the minimum and maximum previous-animation time only when the transition should be limited to a time window.
# Enable transition preview and test every route that can select the target animation.

SOMA's shipped entities contain 204 transition entries. The engine emits separate errors for a missing previous animation, missing transition animation, and missing transition base animation.

== Test from script ==

After preview succeeds, place the entity in a test map and play the registered name:

<syntaxhighlight lang="cpp">
Entity_PlayAnimation("Machine", "open", 0.1f, false, true, "OnAnimationFinished");
</syntaxhighlight>

The SOMA API records the completion callback as:

<syntaxhighlight lang="cpp">
void OnAnimationFinished(const tString &in asEntityName,
const tString &in asAnimName)
{
}
</syntaxhighlight>

Use a loop only for a clip intended to repeat. Leave transition playback enabled only when the entity has a matching transition setup.

== Troubleshooting ==

* '''The file does not appear or load:''' verify the mod-relative path, extension, and resource configuration.
* '''The animation name cannot be played:''' check the entity's registered <code>Name</code>; it can differ from the source filename.
* '''The mesh deforms incorrectly:''' compare the mesh and animation hierarchy, node names, unit metadata, and export axes.
* '''The entity reports a skeleton mismatch:''' reimport the mesh into the entity and confirm that the exported animation targets that same skeleton.
* '''Events do not fire correctly:''' inspect event time, type, value, and socket separately from animation playback.
* '''A transition fails:''' verify that the previous, target, and bridge names all match registered entity animations.
* '''An update still plays old data:''' reload the entity after replacing the source and ensure the generated <code>.anm</code> cache is refreshed.

== See also ==

* [[HPL3/SOMA/Animation/Animation Overview|Animation Overview]]
* [[HPL3/SOMA/Modeling/Exporting Animations|Exporting Animations]]
* [[HPL3/Entities/Adding Animations to Entities|Animation Editor fields]]
* [[HPL3/Entities/Model Preview Settings|Entity Preview]]

[[Category:English]]

HPL3/SOMA/Modeling/Importing Animations - Revision history

TiMan: Add a SOMA-file-verified animation import guide covering entity registration, caches, preview, events, transitions, script testing, and troubleshooting.