Bullettrace and you

Hello all
The bullettrace() function is a very cool and powerful tool for scripters in whole cod.

What is bullettrace()?
Bullettrace is a way to fire a non-visible bullet ("MASK_SHOT"), and get the point where it hits something, the part of the bullettrace that has passed before hitting something, the normal vector of the hit surface and the type of surface that was hit.
It also gives you the entity that was hit (if any)

The inputs for a bullettrace are:

Code:

trace=bullettrace(start,end,hit_players,entity_to_ignore);

trace=
The trace variable is just a random var. I could have used any other name for this variable, but for the sake of the tutorial I will use the most common name for it: trace

bullettrace()
The actual function.

start
The start of the bullettrace. This is a 3-component vector, much like an origin of an entity. It is just a point in a 3d space, like (10,0,5), or player.origin (if player is defined)

End
Same as start, but the end of the bullettrace. The invisible bullet thus travels at infinite speed between the start and the end points.

hit_players
This is a boolean (true or false) which indicates wheter or not you want to hit players. Set this to true to hit players, set it to false to ignore all players while tracing.

entity_to_ignore
This sets the entity you do not want to hit. If you have a map with an entity with the targetname "car_big", you can avoid hitting it using:

Code:

random_var=getent("car_big","targetname"); trace=bullettrace(start,end,hit_players,random_var);

However, you cannot add multiple entities to the ignore list, so think wisely about the start and end position, and the entity to ignore.

So, what does it return?
As said in the intro, it returns:
position
fraction
entity
surfacetype
normal

How does it return these vars?
It returns these vars by the use of an array, in the form of:
trace["position"]
trace["fraction"]
trace["entity"] etc

position:
trace["position"] is the place where the bullet hit something, and it is NOT(!) the origin of the entity that was hit. If nothing has been hit during the trace, the end position will be in this var.

fraction:
trace["fraction"] is the amount of the trace which was covered before it hit something. This var can range from 0 to 1, 0 being no distance traveled at all, and 1 reaching the end position
so, the next 2 ifs are the same:

Code:

trace=bullettrace(start,end,hit_players,entity_to_ignore); if(trace["fraction"]==1) and if(trace["position"]==end)

Both ifs will be run if the bullettrace did not hit anything.

entity:
trace["entity"] is the entity which was hit. If the trace is completed without hitting any entity, it will be undefined. If you want to know wheter or not a certain entity is a player, use:

Code:

trace=bullettrace(start,end,true,entity_to_ignore); if(isdefined(trace["entity"])&&isplayer(trace["entity"]))

Note how I replaced the hit_players with true. As I want to know wheter or not a certain entity is a player, I have to enable hitting players.

surfacetype:
trace["surfacetype"] is a not-so-useful value that is returned nevertheless. It tells you what kind of surface was hit, using a string. Just as with the entity, it will be undefined if nothing was hit.
The following surfacetypes can be determined:

Code:

default bark brick carpet cloth concrete dirt flesh foliage glass grass gravel ice metal mud paper rock sand snow water wood asphalt

normal:
trace["normal"] is the unit normal of the surface you hit. Im not entirely sure about what happens when nothing is hit, wheter it becomes (0,0,0) or undefined, but you have to check the fraction to be able to use this.

I hope you guys think this tutorial is useful