Spatial Orientation and Relative Positions

Rotation Values

The Rotation Value of an entity represents where it's facing in the world. This is stored and used as uint8, meaning that values range 0~255.

⚠️ As such, all degrees on Topaz are based on a "256 degree" scale. This is not the same "360 degree" scale that you may be used to.

Rotation 0 is aligned with as due East, with values increasing as you rotate to the right.

⚠️ Rotation increases going clockwise from 0. This is the opposite of standard Trigonometry.

Rotation Value	Cardinal Direction	(Standard Trig) Pi	"360 Scale" Degree (Clockwise)
0	E	0	0
32	SE	7Pi/4	45
64	S	3Pi/2	90
96	SW	5Pi/4	135
128	W	Pi	180
160	NW	3Pi/4	225
192	N	Pi/2	270
224	NE	Pi/4	315

World Angles

The "World Angle" between Entity A and Entity B is the absolute, cardinal, "world aligned" angle between Entity A and B.

⚠️ Like Rotation Values, they range 0~255. They are not Trigonometry radians. (Although they can be converted to radians.)

Measurements start at 0 for due East, and angles increase going clockwise.

Either entity's Rotation Value is not a factor in the calculation. If the World Angle from Entity A to a "northward" Entity B is 192, the A->B World angle will remain 192 regardless of if Entity A is facing North or South.

These angles are with Entity A as the "origin". If the World Angle from Entity B to Entity A is measured, it will always be the "cardinal opposite" of Entity A to Entity B (not a negative value).

❕ Tip: Because Rotation values and World Angles are both absolutely aligned and on the same scale, having an entity face a given angle (ie: another entity) is as simple as setting the entity's Rotation to the World Angle!

Facing Angles

Facing Angles are the number of degrees from an entity's Rotation to another entity's World Angle. In other words, they're the number of degrees Entity A would need to turn to face Entity B.

An Entity A > Entity B Facing Angle of 0 means that Entity A is directly facing Entity B with no deviation (its Rotation is the same as the A->B World Angle).

As entities can turn in two directions, there would ordinarily be two potential values which could work. However, the Facing Angle is always the lower of the two values.

⚠️ Facing Angles range 0~128. An Entity A > Entity B Facing Angle of 128 means Entity B is directly opposite of where Entity A is facing.

Additionally, Facing Angles are signed to indicate which direction a rotation would need to be to directly face another entity. Negative values are counter-clockwise turns, while positive values are clockwise turns (matching standard Rotation increases).

Facing Value	Shortest Turn Direction	(Standard Trig) Pi	"360 Scale" Degree Turn
-128	Left	Pi/4	180
-96	Left	3Pi/4	135
-64	Left	Pi/2	90
-32	Left	Pi/4	45
0	0	0	0
32	Right	7Pi/4	45
64	Right	3Pi/2	90
96	Right	5Pi/4	135
128	Right	Pi	180

Positional Arcs

The absolute value of the Facing Angle can be compared against certain values to quickly determine where Entity B is, in relation to where Entity A is facing.

⚠️ Remember that the maximum absolute value of a Facing Angle is half a circle. Angles to compare against need to be half as well. Comparisons against these check for both halves of a circle (sides of the mob).

Term	Minimum Absolute Facing Angle	Maximum Absolute Facing Angle	Minimum "360 Scale" Degree	Maximum "360 Scale" Degree
In Front	0	32	0	45
Beside	32	96	45	135
Behind	96	128	135	180