c_move(ENTITY* entity,VECTOR* reldist,VECTOR* absdist,var mode)

The function returns the amount of distance covered. If the entity could not move at all due to being blocked by obstacles, it returns a negative value or 0. If collision events are enabled, they are triggered for the entity as well as for the obstacle. During a collision event, several predefined variables are set to indicate the type of collision (see below). They can be evaluated in the event function for setting collision or ricocheting behavior of any kind.

Parameters:

The following mode flags can be combined:

Depends on:

Returns:

Modified:

Remarks:

• The following collision events can be triggered by c_move collisions. Moving entity: EVENT_BLOCK on collisions with the level, and EVENT_ENTITY on collisions with entities. Hit entity: EVENT_IMPACT, EVENT_PUSH, EVENT_SONAR, or EVENT_SHOOT depending on c_move modes .
• Create collision geometry in a way that entities don't get entangled. Entities that move can get stuck when colliding with polygonal objects with 'hooks' or 'gaps' of just the size of the moving entity. Use a non-polygonal hull or the PASSABLE flag for any object that is shaped in a way that entities can get entangled with it. Set the POLYGON flag for all other models - such as ramps or stairs - that don't move and should serve as obstacles.
• The speed of the function depends on whether a collision is detected or not, and whether the entity is gliding or not. When moving an entity, take care to keep its bounding box (min_x/max_x) small enough for avoiding unnecessary collisions.  !!  A usual beginner's mistake is extending the entities' bounding box all the way to its feet and then apply gravity for pressing the entity against the ground. This is not only slow due to the permanent collisions with the ground, it will also cause the entity to get stuck in any little crack in the floor, and prevent it from ascending stairs or slopes. Rather, use c_trace for keeping the entities' bounding box at a distance from the ground, and apply gravity only above that distance. See the example below for a simple movement function.
• To prevent an entity from moving up a stair you will have to either reduce its forward momentum or increase the gravity. If on the other hand you want to make an entity climb a particularly high stair you would have to increase its forward velocity or reduce gravity. Given sufficiently large velocities an entity can climb any stair that is up to half its size (assuming that c_setminmax was used to set the ellipsoid to be as tall as the entity). For these reasons the Template Scripts use two c_move calls instead. One to handle gravity, the second to handle the forces acting on the player. This is a more flexible solution that allows for more control but is of course slower than a single c_move call.
• If the move ended up inside a passable block, the predefined in_passable variable is set to 1. If the move ended up inside a solid block (which only can happen if passable entities are moved), the in_solid variable is set to 1.
• If GLIDE is set, the function will try to move as far as possible by gliding along surfaces or making way around obstacles. The move_friction variable (range 0..1, default 0.25) determines the friction for gliding along surfaces. At 0 there is no friction at all, at 1 the entity sticks to the surface and does not glide at all. The predefined variable disable_z_glide if set to non-zero disables gliding up slopes or other objects.
• With GLIDE set, the internal movement function is executed multiple times (up to 6 times) to allow the model to glide along walls and other objects. Thus GLIDE can slow down the movement and make the model end up at unexpected places. Never set GLIDE for doors, lifts, etc.
• If ACTIVATE_TRIGGER is set, a nearby entities' event function is triggered when it's ENABLE_TRIGGER flag is set and either a) tThe sum of the moved entities' trigger_range and the nearby entities' trigger_range is bigger than the distance between the move target position and the nearby entities' origin, or b) the nearby entities' trigger_range is zero, its passable flag is set and the move target position is inside it's bounding box.
• The variables move_min_z and move_friction determine the maximum step height and gliding behavior.
• IGNORE_YOU can be used to prevent that a bullet gets stuck immediately within the barrel or within the entity that fired it.  !!  A usual beginner's mistake is setting the IGNORE_YOU flag but not setting the you pointer. This causes the collision detection to fail randomly because you is modified by many functions (including this one).
• Physics entities can't be moved directly - apply a force or velicity instead.

Speed:

Example (lite-C):

// simple function for walking over ground
// control the player with the WASD keys
// player origin must be at the model center
// bounding box must be smaller than the player!
action player_walk()
{ 
// if necessary, adjust the bounding box to give the entity 'floor room' (see remarks) 
// my.min_z *= 0.5;

   var speed_down = 0;   // downward speed by gravity
   var anim_percent = 0; // animation percentage
   VECTOR vFeet;
   vec_for_min(vFeet,me); // vFeet.z = distance from player origin to lowest vertex

   while (1)
   {
// rotate the player using the [A] and [D] keys      
      my.pan += 5*(key_a-key_d)*time_step; 

// determine the ground distance by a downwards trace
      var dist_down; 
      if (c_trace(my.x,vector(my.x,my.y,my.z-5000),IGNORE_ME | IGNORE_PASSABLE | USE_BOX) > 0)
         dist_down = my.z + vFeet.z - target.z; // get distance between player's feet and the ground
      else
         dist_down = 0;

// apply gravity when the player is in the air
      if (dist_down > 0)  // above floor, fall down with increasing speed
         dist_down = clamp(dist_down,0,accelerate(speed_down,5,0.1));
      else                // on or below floor, set downward speed to zero
         speed_down = 0;

// move the player using the [W] and [S] keys      
      var dist_ahead = 5*(key_w-key_s)*time_step;
      dist_ahead = sign(dist_ahead)*(abs(dist_ahead) + 0.5*dist_down); // adapt the speed on slopes
      c_move(me,vector(dist_ahead,0,0),vector(0,0,-dist_down),IGNORE_PASSABLE | GLIDE); // move the player

// animate the player according to its moved distance
      if (dist_ahead != 0) // player is moving ahead
      {
         anim_percent += 1.3*dist_ahead; // 1.3 = walk cycle percentage per quant
         ent_animate(me,"walk",anim_percent,ANM_CYCLE); // play the "walk" animation
      }
      else // player stands still
      { 
         anim_percent += 5*time_step; 
         ent_animate(me,"stand",anim_percent,ANM_CYCLE); // play the "stand" animation
      }
      wait(1);
   }
}

See also:

► latest version online