ent_animate

ent_animate(ENTITY* entity,STRING* scene,var percent,var mode)

Animates a model, terrain or sprite entity by setting it to an interpolated position within a cyclic or non-cyclic animation scene.

Parameters:

entity

Entity to be animated.

scene

Name of the bones or vertex animation scene without the trailing number, or NULL for resetting frame, nextframe , and the entities' skeleton to their default states. Resetting the skeleton is required before combining a bones animation.

percent

Animation percentage within the scene, 0..100. At 0 the first frame is selected, at 100 the last frame (which is identical with the first for cyclic animation).

mode

to be combined from the following predefined values:

ANM_SKIP	For not interpolating the frames.
ANM_CYCLE	Cyclic animation scene, like walking or running. Otherwise it's a noncyclic scene like jumping or shooting.
ANM_ADD	For combining a bones animation from several ent_animate calls. Adds the new bones angles to the current angles, rather than replacing the current angles by the new ones.

Returns:

> 0	number of the target frame for a vertex or sprite scene
< 0	target frame for a bones scene
0	no scene with the given name was found

Modifies:

entity.frame	set to the current vertex or sprite frame plus interpolation factor, in case of a vertex or sprite animation
entity.next_frame	set to the next vertex target frame for interpolation, or reset to 0 , in case of a vertex animation

Speed:

Medium (vertex or sprite animation)
Slow (bones animation)

Remarks:

If the scene contains bones animation, the instruction does not alter the frame and next_frame parameters, but modifies the entity's skeleton. Only bones affected by the given scene are set to their new orientation; bones not affected by this scene keep their old state. By executing this instruction several times for different animation scenes, bones animations are combined. Bones animation can also be combined with vertex animation.
Use ANM_ADD for combining different bones movements even if they affect the same bones. For instance, if a bone was already rotated by 10 degrees and the new scene rotates the same bone by further 20 degrees, the new bones angle is 30 degrees after ent_animate with ANM_ADD. Without ANM_ADD it's new angle is 20 degrees. Bones animation can also be combined with direct bones manipulation through ent_bonerotate or similar instructions.
In a multiplayer game, sending bones animation to the clients causes the high traffic and does not interpolate between bones frames. Only basic frames, without ANM_ADD mode, and without any direct bones manipulation are sent. We strongly recommend to perform bones and vertex animation on the client side by using a local function and setting the entity's nosend_frame flag on the server.
ent_animate(entity,NULL,0,0) resets all bones poses of the entity.
Entity scene and bone names must consist of at least 3 characters. For finding the scene, only the length of the scene string is compared. Therefore models must not contain scene names that begin with the complete name of another scene.

Edition:

C P for bones frames. Vertex and sprite frames can be set with all editions.

Examples:

action vertex_anim()
{
   while() 
   {
      my.skill1 += 3*time_step;
      if (my.skill1 > 100) my.skill1 -= 100; 
      ent_animate(me,"walk",my.skill1,ANM_CYCLE);
      wait(1);
   }
}

// let a model run, and smoothly blend over to shooting when [Ctrl] is pressed
action bones_anim()
{
   while(1)
   {
      my.skill1 += 3*time_step; // torso animation
      my.skill2 += 3*time_step; // legs animation

      if (key_ctrl) // fire key pressed?
      {
         my.skill3 += 20*time_step; // blend factor for 1-frame shooting animation
         my.skill3 = min(my.skill3,100); // clip at 100 percent
      } else {
         my.skill3 -= 20*time_step;
         my.skill3 = max(my.skill3,0); // clip at 0 percent
      }

// reset skeletion and then compose the animation (order is important): 
      ent_animate(me,NULL,0,0); // reset all bones
// first, shake the arms during running
      ent_animate(me,"run_torso",my.skill1,ANM_CYCLE);
// then blend over to, or blend back from shooting (only affects the arms)
      if (my.skill3 > 0) { ent_blend("shoot",0,my.skill3); }
// finally animate the legs (only affects the legs)
      ent_animate(me,"run_legs",my.skill2,ANM_CYCLE+ANM_ADD);
     
      wait(1);
  }
}