returns the distance between two points
example: p1=(0,0,0) p2=(10,0,0)
the distance is 10 so the return value will be 10
If speed is important it is better to use STATE_math_get_square_distance()
which is much faster because it doesn't do the sqrt()