Syntax:c trace
From GameStudio Wiki
Function: c_trace
|
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.
Contents |
[edit]
Definition
c_trace(VECTOR* from, VECTOR* to, var mode)
[edit]
Parameters
- from
- type
- description
- Start position
- to
- type
- description
- Target position
- mode
- type
- value range
- (see Tracing Modes)
- description
- Start position
[edit]
Tracing Modes
- IGNORE_ME
- Ignores the me entity.
- IGNORE_YOU
- Ignores the you entity.
- 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_MAPS
- Ignores all map and terrain 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
- Use 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.
- GET_HITVERTEX
- When a model is hit, the number of the hit vertex will be returned in the hitvertex variable. Mutually exclusive with USE_AABB.
- SCAN_TEXTURE
- Used to give actors some kind of vision, by retrieving the texture name, flags, brightness and light color of the hit surface. Mutually exclusive with USE_BOX.
The predefined string tex_name and the variables 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. Through the str_cmpi instruction, the floor texture name can be determined and some different walking behavior can be set. Another possibility is using tex_light to make a player invisible for his enemies when he hides in the shadows.
[edit]
Modifies
- 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) of the hit texture.
- tex_color
- Color of the static light reflected by the hit texture.
- hitvertex
- The hit object's closest vertex number, when mode is set to GET_HITVERTEX.
- event_type
- EVENT_SHOOT or EVENT_SONAR (depends on mode)
[edit]
Returns
- > 0
- Distance to the hit polygon of the next obstacle.
- 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.
[edit]
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.
[edit]
Example
// test the floor texturevec_set(temp, my.x); temp.z -= 500; // trace downwards 500 quants below c_trace (my.x,temp,IGNORE_ME|IGNORE_PASSABLE|IGNORE_MODELS|IGNORE_SPRITES|SCAN_TEXTURE); // now TEX_NAME is set to the floor name below the MY entity ... // look if the YOU enemy can be shot at from my position, and if yes, hurt him c_trace (my.x,your.x,IGNORE_ME|IGNORE_PASSABLE|ACTIVATE_SHOOT); // if entity YOU was visible from MY position, its SHOOT event was triggered
[edit]
