c_move

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

Moves an entity over a certain distance while performing collision detection, triggering collision events, and gliding along obstacles.

The first vector reldist gives a relative distance and direction in rotated entity coordinates, i.e. the direction that the entity is facing. The second vector absdist gives an absolute distance and direction in world coordinates. The resulting movement is a combination of both distances. Normally the first vector is used for the propelling speed of the entity, and the second one for external forces, like gravity and drift. To zero one of these vectors, the predefined nullvector can be given.

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:

entity	Entity to be moved.
reldist	Move distance vector in entity coordinates
absdist	Move distance vector in world coordinates
mode	Collision mode, see below.

The following mode flags can be combined:

IGNORE_YOU	Ignores the you entity on collision detection (see remark).
IGNORE_FLAG2	A7.05 Ignores all entities with FLAG2 set.
IGNORE_PASSABLE	Ignores all passable blocks and entities, including all water entities.
IGNORE_PASSENTS	Ignores passable model and sprite entities, but still detects water entities (rectangular passable maps, or passable terrain). It sets the predefined flags in_passable and on_passable . The predefined passable_ent pointer is set to the detected water entity. This can be used, for example, to switch the player behavior to swimming.
IGNORE_WORLD	Ignores all level blocks and terrains.
IGNORE_MAPS	Ignores all map entities.
IGNORE_MODELS	Ignores all models.
IGNORE_SPRITES	Ignores all sprites.
IGNORE_PUSH	Ignores all entities with lower push values than the given entity, and triggers the EVENT_PUSH collision event on those entities.
IGNORE_CONTENT	Ignores the content of the move origin. The function is faster, but water entities (see above) are not detected.
ACTIVATE_TRIGGER	Enables EVENT_TRIGGER during the motion. Can be slow.
ACTIVATE_PUSH	A7.05 Triggers the EVENT_PUSH collision event on the hit entity, regardless of the push value. If the event function returns 1, the hit entity is considered an obstacle; if the event function returns 0, it is ignored. This way individual collision groups can be defined.
ACTIVATE_SHOOT	A7.07 Enables EVENT_SHOOT triggering of the hit entity, and prevents all other collision events. This flag lets c_move behave similar to c_trace.
ACTIVATE_SONAR	A7.07 Enables EVENT_SONAR triggering of the hit entity, and prevents all other collision events. This flag lets c_move behave similar to c_trace.
USE_AABB	Uses an axis aligned bounding box (AABB) for collision, rather than an oriented bounding box (OBB). The AABB system is faster, but ignores the entity orientation on USE_BOX, treats models and sprites as boxes, and requires a BSP level. See collision for the difference between both systems.
GLIDE	Glides along walls and entities on impact.

Depends on:

move_friction	Friction factor for gliding along walls.
move_min_z	Maximum step height (OBB only).
disable_z_glide	Disables gliding up slopes (OBB only).

Returns:

> 0	Distance covered.
<= 0	Entity was blocked.

Modified:

target	Position of the collision contact.
normal	Normal vector of the colliding surface.
bounce	Bounce off direction vector.
trace_hit	Set to nonzero when something was hit.
in_passable	Set to nonzero when the starting or ending point is inside a water entity.
on_passable	Set to nonzero when the hit target is a water entity.
passable_ent	When in_passable or on_passable is set, this pointer is set to the detected water terrain (OBB system only).
event_type	Type of event when one was triggered.

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.
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, avoid unnecessary collisions with the ground. Do not use gravity to press the entity against the ground. Rather, use c_trace for keeping the entities' bounding box at a distance from the ground, and apply gravity only above that distance.
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).

Speed:

Slow

Example:

result = c_move(me,vector(5*time_step,0,0),nullvector,IGNORE_YOU|GLIDE);