HPL3/SOMA/Animation/Animation Overview

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:

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

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

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

Entity animation registration

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

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

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

Attribute	Purpose established by SOMA data
Name	Name used by scripts and entity behavior to select the animation.
File	Mod-relative path to the exported animation source.
Layer	Animation layer. Default is present on 1,387 of the 1,490 inspected registrations; 103 registrations omit this attribute.
Speed	Playback-speed multiplier. 1 is the most common shipped value, but SOMA also uses values below and above 1.
SpecialEventTime	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 .dae_anim 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 .ent 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 Name, Time, Type, DestSocket, and Value. Event types used by shipped SOMA entities are:

• PlaySound
• PlayLoopSound
• StopLoopSound
• CreateParticle
• Message

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

For example, robot_arm_welding.ent attaches looped movement sound, weld sounds, particle creation at named sockets, and a stop-loop event to its welding 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:

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 = ""
);

The callback signature recorded by the SOMA API is:

void Callback(const tString &in asEntityName, const tString &in asAnimName)

For entities with a character-mover component, CharMover_PlayAnimation 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

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

See also

• Exporting Animations
• Importing Animations
• Animation registration controls
• Entity Preview controls
• Lip Sync