- Calculates the arctangent of dy/dx, the angle formed by the vector on the unit circle. The result is adjusted to represent the full circle.
- dx
-
- The horizontal component.
- dy
-
- The vertical component.
- return-value
-
- The angle of the line from 0,0 to dx,dy.
The atan2() function calculates the arctangent (the inverse tangent) of the ratio of two numbers, dy/dx. Where dx is a change in horizontal position and dy is a change in vertical position, the arctangent is the angle formed by the line from the center of the circle to that position.
PICO-8 adjusts the arctangent value based on the signs of dx and dy such that every angle of the circle is represented. For example, atan2(1, 1) is 0.875 (7/4 pi radians, or 315 degrees), and atan2(-1, -1) is 0.375 (3/4 pi radians, or 135 degrees). Similarly, atan2(0, 1) is 0.75.
The Wikia articles on sin() and cos() establish a convention where the angle runs clockwise and sine values maintain the traditional orientation, e.g. sin(0.125) is -0.7071 (negative goes down):
Using this convention, you must invert the sign of dy to understand the result of atan2().
The official PICO-8 documentation use the alternative convention, where angles run counterclockwise and sin() is simply understood to return the negative of the traditional result. This convention allows the arguments to atan2() to be understood as changes in screen coordinates (increasing y values go down). The two conventions are mathematically equivalent.
Examples[]
print(atan2(1, 0)) -- 0
print(atan2(1, 1)) -- 0.875
print(atan2(0, 1)) -- 0.75
print(atan2(-1, 1)) -- 0.625
print(atan2(-1, 0)) -- 0.5
print(atan2(-1, -1)) -- 0.375
print(atan2(0, -1)) -- 0.25
print(atan2(1, -1)) -- 0.125
-- longer vector uses the ratio
print(atan2(99, 99)) -- 0.875
-- special case: dx=0, dy=0
print(atan2(0, 0)) -- 0.25