TiMan: Add a SOMA-file-verified animation overview covering source/cache formats, entity registration, skeleton compatibility, events, transitions, scripting, and workflow.

2026-10-02T17:16:47Z

Add a SOMA-file-verified animation overview covering source/cache formats, entity registration, skeleton compatibility, events, transitions, scripting, and workflow.

New page

An '''animation''' changes an entity's mesh over time. In SOMA, an exported animation source is registered on an entity under a playable name. Scripts and entity logic play that registered name rather than referring to the source filename directly.

== Animation pipeline ==

A typical SOMA animation passes through four stages:

# A mesh and its skeleton or animated nodes are prepared in a 3D application.
# Each animation clip is exported to a source file, usually <code>.dae_anim</code> or <code>.fbx</code> in the shipped game.
# The clip is added to an entity's <code>Animations</code> section in <code>ModelEditor.exe</code>, where it receives a name and playback settings.
# Loading the source produces an <code>.anm</code> cache used by the engine.

The installed SOMA entities contain 1,490 animation registrations. Of these, 1,379 reference <code>.dae_anim</code> files and 110 reference <code>.fbx</code> files. After deduplicating those registrations, 879 referenced source files are present in the installation; 866 have a same-stem <code>.anm</code> cache.

The source file remains the editable input. The <code>.anm</code> is generated engine data, not a replacement for the source animation.

== Entity animation registration ==

Animations are stored inside the entity's <code>Animations</code> element. A simple shipped registration is:

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

This entry belongs to <code>entities/urban/toilet/shower_curtain/shower_curtain.ent</code>. The same entity's mesh is <code>shower_curtain.fbx</code>; the entity records seven bones and uses a separate <code>shower_curtain_open.anm</code> cache for the animation source.

{| class="wikitable"
! Attribute !! Purpose established by SOMA data
|-
| <code>Name</code> || Name used by scripts and entity behavior to select the animation.
|-
| <code>File</code> || Mod-relative path to the exported animation source.
|-
| <code>Layer</code> || Animation layer. <code>Default</code> is present on 1,387 of the 1,490 inspected registrations; 103 registrations omit this attribute.
|-
| <code>Speed</code> || Playback-speed multiplier. <code>1</code> is the most common shipped value, but SOMA also uses values below and above 1.
|-
| <code>SpecialEventTime</code> || Optional stored time value present on 103 inspected registrations. Its exact runtime purpose is not documented by the inspected scripts, so it should not be assigned a meaning without testing.
|}

== Skeleton and channel compatibility ==

An animation source contains channels targeting named nodes or bones. All 876 installed <code>.dae_anim</code> files parsed successfully and contain at least one channel. Targets include transformation matrices, translation, rotation, scale, and visibility.

The animation must match the entity mesh's expected hierarchy closely enough for those targets to resolve. SOMA's executable reports specific errors when:

* the skeleton stored in the mesh differs from the skeleton saved in the <code>.ent</code> file;
* vertices in a skinned submesh are not connected to a bone;
* a vertex is influenced by more than four bones; or
* an animation, transition animation, previous animation, or socket cannot be found.

Treat bone and node names as stable identifiers. Re-exporting the mesh with renamed or reorganized bones can invalidate both saved entity data and existing animation clips.

== Events and transitions ==

Animation behavior can be extended in the Model Editor without changing the source clip.

=== Events ===

An event is attached to a time in a registered animation. The 580 inspected shipped event entries all store <code>Name</code>, <code>Time</code>, <code>Type</code>, <code>DestSocket</code>, and <code>Value</code>. Event types used by shipped SOMA entities are:

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

The engine also declares a <code>Step</code> event type, although no shipped event of that type was found in the inspected entity registrations.

For example, <code>robot_arm_welding.ent</code> attaches looped movement sound, weld sounds, particle creation at named sockets, and a stop-loop event to its <code>welding</code> animation.

=== Transitions ===

A transition selects a bridging animation when changing from a specified previous animation to the target animation. SOMA's shipped entities contain 204 transition entries. Their stored fields include the transition name, bridging animation name, optional previous-animation name, and minimum/maximum timing values.

Transitions are entity registration data. The source clips for the base and bridge animations must each be exported and registered before the transition can resolve them.

== Playing a registered animation ==

SOMA's script API exposes:

<syntaxhighlight lang="cpp">
void Entity_PlayAnimation(
const tString &in asEntityName,
const tString &in asAnimation,
float afFadeTime = 0.1f,
bool abLoop = false,
bool abPlayTransition = true,
const tString &in asCallback = ""
);
</syntaxhighlight>

The callback signature recorded by the SOMA API is:

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

For entities with a character-mover component, <code>CharMover_PlayAnimation</code> provides the same animation name, fade, loop, transition, and callback concepts through that component.

SOMA also exposes functions to stop an entity animation, pause or resume a named animation, set its relative time position, and receive message-event callbacks.

== Practical workflow ==

# Export one short clip using the same mesh hierarchy, node names, scale convention, and axis setup as the entity mesh.
# Add the clip to the entity in the Model Editor and give it a unique, stable <code>Name</code>.
# Leave <code>Speed</code> at <code>1</code> for the first test and use the default layer unless the entity has a verified layered setup.
# Open Entity Preview, select the registered animation, and test playback, looping, the skeleton display, and the timeline.
# Add events only after basic playback works. Verify referenced sockets, sounds, and particle systems separately.
# Add transitions only after every base and bridge animation plays by itself.
# Save the entity, place it in a test map, and play the registered name from the relevant entity logic or script.

== See also ==

* [[HPL3/SOMA/Modeling/Exporting Animations|Exporting Animations]]
* [[HPL3/SOMA/Modeling/Importing Animations|Importing Animations]]
* [[HPL3/Entities/Adding Animations to Entities|Animation registration controls]]
* [[HPL3/Entities/Model Preview Settings|Entity Preview controls]]
* [[HPL3/SOMA/Audition/Lip Sync|Lip Sync]]

[[Category:English]]

HPL3/SOMA/Animation/Animation Overview - Revision history

TiMan: Add a SOMA-file-verified animation overview covering source/cache formats, entity registration, skeleton compatibility, events, transitions, scripting, and workflow.