c_trace(VECTOR* from, VECTOR* to, var mode)

Sends a ray from the from position to the to position and checks whether this ray hits an obstacle on its way. This is the general instruction that is used by entities to detect their environment. Alternatively to a ray, the detection probe can be an arbitrarily oriented ellipsoid, sphere, or flat disk, which covers all imaginable collision detection situations.


from Start position vector
to Target position vector
mode Tracing mode, see below

The following mode flags can be combined:

IGNORE_ME Ignores the me entity.
IGNORE_YOU Ignores the you entity (see remark) and does not set the you pointer.
IGNORE_FLAG2 Ignores all entities with FLAG2 set (see also c_ignore).
IGNORE_PASSABLE Ignores all passable blocks and entities.
IGNORE_PASSENTS Ignores passable model and sprite entities, but still detects passable maps, or passable terrain.
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 entities with a lower push or same group value than the given entity. For ignoring certain entity groups, call c_ignore before c_trace.
IGNORE_CONTENT Ignores the content of the trace origin. The function is faster, but water entities (see above) are not detected.
USE_POLYGON Uses a polygonal hull of all target entities even if their POLYGON flag is not set. Only for entities with a collision model, i.e. when the WED PASSABLE flag was not set and collision_mode not deactivated at entity creation.
USE_BOX Uses the size, orientation, and shape of the bounding ellipsoid of the me entity as a 'probe' for tracing, rather than a line. The ellipsoid can be set up temporarily to the desired shape such as a sphere or a flat disk. A vertical trace with USE_BOX can detect the minimum ground distance within a round area, while ignoring small holes or grates.
ACTIVATE_SHOOT Enables EVENT_SHOOT triggering of all hit entities.
ACTIVATE_SONAR Enables EVENT_SONAR triggering of all hit entities.
SCAN_TEXTURE Retrieves the texture name, vertex number, flags, brightness and light color of the hit surface, and sets it in the hit struct. Mutually exclusive with USE_BOX. If nothing was hit, the parameters are not set. The texture name can be used to check the kind of floor below an entity.


> 0 Distance to the hit polygon of the target or of the next obstacle in the way.
<= 0 No polygon was hit.


hit Information about the hit position, normal, texture, and entity  LC .
you Modified when IGNORE_YOU is not set.
tex_flag1..8 Reflect the Flag1..Flag8 states of the hit surface.
tex_fog The fog / albedo value of the hit texture.
event_type EVENT_SHOOT or EVENT_SONAR (depends on mode)


Slow (especially with USE_BOX)



// test the floor texture - trace downwards 1000 quants below
function print_floor_texture()
  c_trace (my.x,vector(my.x,my.y,my.z-1000),IGNORE_ME|IGNORE_PASSABLE|SCAN_TEXTURE);
  if (hit.texname) printf("Floor texture: %s",hit.texname);

// place an entity onto the ground below
function item_set_to_ground()
my.z = hit.z - my.min_z; }
// look if the YOU enemy can be shot at from my position, and if yes, trigger its EVENT_SHOOT event c_trace(my.x,your.x,IGNORE_ME|IGNORE_PASSABLE|ACTIVATE_SHOOT|IGNORE_CONTENT); // trace 1000 units in direction the my entity is facing c_trace(my.x,vec_rotate(vector(1000,0,0),my.pan),IGNORE_ME|IGNORE_PASSABLE|ACTIVATE_SHOOT|IGNORE_CONTENT);

See also:

c_scan, c_move, c_rotate, c_ignore, ent_nextvertex, collision, hit, terrain_height

► latest version online