c_trace

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.

Parameters:

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).
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 me entity.
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. Mutually exclusive with USE_AABB.
USE_BOX	Uses the bounding box or bounding ellipsoid of the me entity for tracing a 'thick' ray rather than a line. This is as if a c_move would be performed up to the target position. A vertical trace with USE_BOX is used by the template scripts for detecting the distance to the ground, keeping the entities' feet on the floor. Small holes or grates will appear filled out when USE_BOX is set.
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.
ACTIVATE_SHOOT	Enables EVENT_SHOOT triggering of the hit entity.
ACTIVATE_SONAR	Enables EVENT_SONAR triggering of the hit entity.
SCAN_TEXTURE	Retrieves the texture name, vertex number, flags, brightness and light color of the hit surface. Mutually exclusive with USE_BOX. The predefined string tex_name and the variables hitvertex, tex_flag1..tex_flag8, tex_light, tex_color and tex_fog are modified according to the hit object (see below). If nothing was hit, tex_name and the other parameters are not set. The texture name can be used to check the kind of floor below an entity.

Returns:

> 0	Distance to the hit polygon of the target or of the next obstacle in the way.
0	No polygon was hit.
< 0	A polygon was hit from behind. The from position lies within a solid object, or the me entity intersects with a target entity.

Modifies:

hit	Contact information (A7.08).
target	Position where the ray hits the surface of the obstacle (maybe to place a blood stain there).
normal	The normal of the hit surface.
you	If the obstacle was an entity, the you pointer is set to that entity; otherwise it's set to NULL
trace_hit	Nonzero if c_trace hit something, otherwise 0.
in_passable	Set when the starting or ending point is inside a water entity.
on_passable	Set 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).
tex_name	Texture name of the surface hit by the ray, or the entity file name if a model, sprite, or terrain was hit.
tex_flag1..8	Reflect the Flag1..Flag8 states of the hit texture.
tex_light	Shadow brightness (0..255) at the hit position.
tex_color	COLOR vector, color of the lightmap at the hit position.
tex_fog	The fog / albedo value of the hit texture.
hitvertex	The hit object's closest vertex number when hitting a polygonal target hull in OBB mode.
event_type	EVENT_SHOOT or EVENT_SONAR (depends on mode)

Speed:

Slow

Remarks:

The bigger the distance between the to and from positions, the more entities must be checked in the level, and the slower is the function. Use as small a distance as possible.
In USE_BOX mode the speed of the function depends on the ray volume, so it's especially important to keep the distance to the to position short. Don't set USE_BOX when a ray trace would suffice.
In USE_BOX mode the targets are always considered polygonal (as if USE_POLYGON were set). The hull must not intersect the target. The result delivered back gives the distance from the hit point to the nearest point of the hull of the me entity. If the entity touches the target in USE_BOX mode, 0 or a very small distance value is delivered back. As 0 is also used for indicating no hit, check the trace_hit value.
IGNORE_YOU can be used to prevent detection of a certain entity. !! A usual beginner's mistake is setting the IGNORE_YOU flag but not setting the you pointer. This causes the detection to fail randomly because you is modified by many functions (including this one).
For hitting an entity, trace to a point well nside the entity mesh, such as the entity center. !! A usual beginner's mistake is using a vertex of the entity mesh for the trace target. This will miss the entity randomly because depending on its position or orientation, the trace ends just before touching the mesh surface.

Examples:

// 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()
{
  c_trace(my.x,vector(my.x,my.y,my.z-1000),IGNORE_ME|IGNORE_SPRITES);
  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
function shoot_you()
{
  c_trace (my.x,your.x,IGNORE_ME|IGNORE_PASSABLE|ACTIVATE_SHOOT); 
}